webext-messenger 0.33.0-1 → 0.33.0-3

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} handler 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/sender.js

@@ -1,7 +1,7 @@
 import pRetry from "p-retry";
-import { isBackground } from "webext-detect";
+import { isBackground, isExtensionContext } from "webext-detect";
 import { deserializeError } from "serialize-error";
-import { isObject, MessengerError, __webextMessenger } from "./shared.js";
+import { isObject, MessengerError, ExtensionNotFoundError, __webextMessenger, } from "./shared.js";
 import { log } from "./logging.js";
 import { handlers } from "./handlers.js";
 import { events } from "./events.js";
@@ -10,6 +10,7 @@ const _errorTargetClosedEarly = "A listener indicated an asynchronous response b
 export const errorTargetClosedEarly = "The target was closed before receiving a response";
 export const errorTabDoesntExist = "The tab doesn't exist";
 export const errorTabWasDiscarded = "The tab was discarded";
+const errorExtensionNotFound = "Extension $ID is not installed or externally connectable";
 function isMessengerResponse(response) {
     return isObject(response) && response["__webextMessenger"] === true;
 }
@@ -78,7 +79,12 @@ async function manageMessage(type, target, seq, retry, sendMessage) {
                     attemptCount: error.attemptNumber,
                 },
             }));
-            if (wasContextInvalidated()) {
+            if ("extensionId" in target &&
+                error.message === _errorNonExistingTarget) {
+                // The extension is not available and it will not be. Do not retry.
+                throw new ExtensionNotFoundError(errorExtensionNotFound.replace("$ID", target.extensionId));
+            }
+            if (isExtensionContext() && wasContextInvalidated()) {
                 // The error matches the native context invalidated error
                 // *.sendMessage() might fail with a message-specific error that is less useful,
                 // like "Sender closed without responding"
@@ -142,6 +148,9 @@ function messenger(type, options, target, ...args) {
     options.seq = globalSeq++;
     const { seq } = options;
     if ("extensionId" in target) {
+        if (!globalThis.chrome?.runtime?.sendMessage) {
+            throw new ExtensionNotFoundError(errorExtensionNotFound.replace("$ID", target.extensionId));
+        }
         const sendMessage = async (attemptCount) => {
             log.debug(type, seq, "↗️ sending message to extension", attemptLog(attemptCount));
             return chrome.runtime.sendMessage(target.extensionId, makeMessage(type, args, target, options));

package/distribution/shared.d.ts

@@ -10,6 +10,9 @@ export declare function isObject(value: unknown): value is Record<string, unknow
 export declare class MessengerError extends Error {
     name: string;
 }
+export declare class ExtensionNotFoundError extends MessengerError {
+    name: string;
+}
 export declare function isErrorObject(error: unknown): error is ErrorObject;
 export declare function delay(milliseconds: number): Promise<void>;
 export declare function once<Callback extends (...arguments_: unknown[]) => unknown>(function_: Callback): Callback;

package/distribution/shared.js

@@ -6,6 +6,9 @@ export function isObject(value) {
 export class MessengerError extends Error {
     name = "MessengerError";
 }
+export class ExtensionNotFoundError extends MessengerError {
+    name = "ExtensionNotFoundError";
+}
 addKnownErrorConstructor(MessengerError);
 export function isErrorObject(error) {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- This is a type guard function and it uses ?.

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-3",
   "description": "Browser Extension component messaging framework",
   "keywords": [],
   "repository": "pixiebrix/webext-messenger",