webext-messenger 0.33.0-1 → 0.33.0-2

package/distribution/receiver.d.ts

@@ -2,6 +2,6 @@ import { type Message, type ExternalMessage, type MessengerMeta } from "./types.
 export declare function isMessengerMessage(message: unknown): message is Message;
 export declare function isExternalMessengerMessage(message: unknown): message is ExternalMessage;
 export declare function registerMethods(methods: Partial<MessengerMethods>): void;
-export declare function allowExternalUse(...types: Array<keyof MessengerMethods>): void;
+export declare function exposeMethodsToExternalMessaging(...types: Array<keyof MessengerMethods>): void;
 /** Ensure/document that the current function was called via Messenger */
 export declare function assertMessengerCall(_this: MessengerMeta): asserts _this is MessengerMeta;

package/distribution/receiver.js

@@ -14,13 +14,10 @@ export function isMessengerMessage(message) {
         Array.isArray(message["args"]));
 }
 export function isExternalMessengerMessage(message) {
-    return (isObject(message) &&
-        typeof message["type"] === "string" &&
-        message["__webextMessenger"] === true &&
-        Array.isArray(message["args"]) &&
-        isObject(message["target"]) &&
-        Object.keys(message["target"]).length === 1 && // Ensure it's *only* `extensionId`
-        typeof message["target"]["extensionId"] === "string");
+    return (isMessengerMessage(message) &&
+        isObject(message.target) &&
+        Object.keys(message.target).length === 1 && // Ensure it's *only* `extensionId`
+        typeof message.target.extensionId === "string");
 }
 /**
  * Decides what to do with a message and sends a response (value or error) back to the sender.
@@ -69,13 +66,16 @@ function onMessageListener(message, sender, sendResponse) {
             sendResponse({ __webextMessenger, error: serializeError(error) });
         }
     })();
-    // This indicates that the message is being handled and a response will be sent asynchronously
-    // TODO: Just return a promise if this is ever implemented https://issues.chromium.org/issues/40753031
+    // This indicates that the message is being handled and a response will be sent asynchronously.
+    // It can be improved if this is ever implemented https://issues.chromium.org/issues/40753031
     return true;
 }
-// Do not remove.
-// Early validation to ensure that the message matches the specific allowed target
-// before letting it flow into the rest of messenger.
+/**
+ * Early validation to ensure that the message matches the specific allowed target
+ * before letting it flow into the rest of messenger. An malicious message might
+ * otherwise pass internal checks and be forwarded to the wrong context.
+ * @warn Do not remove. Keep as a security measure.
+ */
 function onMessageExternalListener(message, sender, sendResponse) {
     if (isExternalMessengerMessage(message) &&
         message.target.extensionId === chrome.runtime.id) {
@@ -95,7 +95,7 @@ async function prepareResponse(message, action, meta) {
     const localHandler = handlers.get(type);
     if (localHandler) {
         if ("extensionId" in target && !externalMethods.has(type)) {
-            throw new MessengerError(`${type} is not allowed to be called externally in ${getContextName()}`);
+            throw new MessengerError(`The ${type} is registered in ${getContextName()} for internal use only`);
         }
         return localHandler.apply(meta, args);
     }
@@ -120,7 +120,7 @@ export function registerMethods(methods) {
         chrome.runtime.onMessageExternal.addListener(onMessageExternalListener);
     }
 }
-export function allowExternalUse(...types) {
+export function exposeMethodsToExternalMessaging(...types) {
     for (const type of types) {
         externalMethods.add(type);
     }

package/distribution/sender.d.ts

@@ -1,15 +1,15 @@
-import { type PublicMethod, type PublicMethodWithTarget, type Options, type AnySpecificTarget, type PageTarget } from "./types.js";
+import { type PublicMethod, type PublicMethodWithTarget, type Options, type AnyTarget, type PageTarget } from "./types.js";
 import { type Promisable, type SetReturnType } from "type-fest";
 export declare const errorTargetClosedEarly = "The target was closed before receiving a response";
 export declare const errorTabDoesntExist = "The tab doesn't exist";
 export declare const errorTabWasDiscarded = "The tab was discarded";
 declare function messenger<Type extends keyof MessengerMethods, Method extends MessengerMethods[Type]>(type: Type, options: {
     isNotification: true;
-}, target: AnySpecificTarget, ...args: Parameters<Method>): void;
-declare function messenger<Type extends keyof MessengerMethods, Method extends MessengerMethods[Type], ReturnValue extends Promise<ReturnType<Method>>>(type: Type, options: Options, target: AnySpecificTarget, ...args: Parameters<Method>): ReturnValue;
-declare function getMethod<Type extends keyof MessengerMethods, Method extends MessengerMethods[Type], PublicMethodType extends PublicMethod<Method>>(type: Type, target: Promisable<AnySpecificTarget>): PublicMethodType;
+}, target: AnyTarget, ...args: Parameters<Method>): void;
+declare function messenger<Type extends keyof MessengerMethods, Method extends MessengerMethods[Type], ReturnValue extends Promise<ReturnType<Method>>>(type: Type, options: Options, target: AnyTarget, ...args: Parameters<Method>): ReturnValue;
+declare function getMethod<Type extends keyof MessengerMethods, Method extends MessengerMethods[Type], PublicMethodType extends PublicMethod<Method>>(type: Type, target: Promisable<AnyTarget>): PublicMethodType;
 declare function getMethod<Type extends keyof MessengerMethods, Method extends MessengerMethods[Type], PublicMethodWithDynamicTarget extends PublicMethodWithTarget<Method>>(type: Type): PublicMethodWithDynamicTarget;
-declare function getNotifier<Type extends keyof MessengerMethods, Method extends MessengerMethods[Type], PublicMethodType extends SetReturnType<PublicMethod<Method>, void>>(type: Type, target: Promisable<AnySpecificTarget>): PublicMethodType;
+declare function getNotifier<Type extends keyof MessengerMethods, Method extends MessengerMethods[Type], PublicMethodType extends SetReturnType<PublicMethod<Method>, void>>(type: Type, target: Promisable<AnyTarget>): PublicMethodType;
 declare function getNotifier<Type extends keyof MessengerMethods, Method extends MessengerMethods[Type], PublicMethodWithDynamicTarget extends SetReturnType<PublicMethodWithTarget<Method>, void>>(type: Type): PublicMethodWithDynamicTarget;
 export { messenger, getMethod, getNotifier };
 export declare const backgroundTarget: PageTarget;

package/distribution/targetLogic.d.ts

@@ -1,3 +1,3 @@
-import { type AnyTarget, type Sender } from "./types.js";
-export declare function compareTargets(to: AnyTarget, thisTarget: AnyTarget): boolean;
-export declare function getActionForMessage(from: Sender, target: AnyTarget, thisTarget: AnyTarget): "respond" | "forward" | "ignore";
+import { type LooseTarget, type Sender } from "./types.js";
+export declare function compareTargets(to: LooseTarget, thisTarget: LooseTarget): boolean;
+export declare function getActionForMessage(from: Sender, target: LooseTarget, thisTarget: LooseTarget): "respond" | "forward" | "ignore";

package/distribution/thisTarget.d.ts

@@ -1,4 +1,4 @@
-import { type AnyTarget, type KnownTarget, type TopLevelFrame, type MessengerMeta, type FrameTarget } from "./types.js";
+import { type LooseTarget, type KnownTarget, type TopLevelFrame, type MessengerMeta, type FrameTarget } from "./types.js";
 /**
  * @file This file exists because `runtime.sendMessage` acts as a broadcast to
  * all open extension pages, so the receiver needs a way to figure out if the
@@ -22,7 +22,7 @@ import { type AnyTarget, type KnownTarget, type TopLevelFrame, type MessengerMet
 export declare const thisTarget: KnownTarget;
 declare let tabDataStatus: "needed" | "pending" | "received" | "not-needed" | "error";
 export declare function getTabDataStatus(): typeof tabDataStatus;
-export declare function __getTabData(this: MessengerMeta): AnyTarget;
+export declare function __getTabData(this: MessengerMeta): LooseTarget;
 export declare function getThisFrame(): Promise<FrameTarget>;
 export declare function getTopLevelFrame(): Promise<TopLevelFrame>;
 export declare function initPrivateApi(): void;

package/distribution/types.d.ts

@@ -10,7 +10,7 @@ declare global {
         _: Method;
     }
 }
-type WithTarget<Method> = Method extends (...args: infer PreviousArguments) => infer TReturnValue ? (target: AnySpecificTarget, ...args: PreviousArguments) => TReturnValue : never;
+type WithTarget<Method> = Method extends (...args: infer PreviousArguments) => infer TReturnValue ? (target: AnyTarget, ...args: PreviousArguments) => TReturnValue : never;
 type ActuallyOmitThisParameter<T> = T extends (...args: infer A) => infer R ? (...args: A) => R : T;
 /** Removes the `this` type and ensure it's always Promised */
 export type PublicMethod<Method extends ValueOf<MessengerMethods>> = Asyncify<ActuallyOmitThisParameter<Method>>;
@@ -43,7 +43,7 @@ export interface Options {
 export type Message<LocalArguments extends Arguments = Arguments> = {
     type: keyof MessengerMethods;
     args: LocalArguments;
-    target: AnySpecificTarget;
+    target: AnyTarget;
     /** If the message is being sent to an intermediary receiver, also set the options */
     options?: Options;
 };
@@ -55,7 +55,8 @@ export type MessengerMessage = Message & {
     /** Guarantees that a message is meant to be handled by this library */
     __webextMessenger: true;
 };
-export interface AnyTarget {
+/** A loose union to simplify the internal checks. */
+export interface LooseTarget {
     tabId?: number | "this";
     frameId?: number | "allFrames";
     page?: string;
@@ -85,5 +86,5 @@ export interface PageTarget {
 export interface ExtensionTarget {
     extensionId: string;
 }
-export type AnySpecificTarget = Target | PageTarget | ExtensionTarget;
+export type AnyTarget = Target | PageTarget | ExtensionTarget;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webext-messenger",
-  "version": "0.33.0-1",
+  "version": "0.33.0-2",
   "description": "Browser Extension component messaging framework",
   "keywords": [],
   "repository": "pixiebrix/webext-messenger",