@matter/protocol 0.16.0-alpha.0-20250913-0bc2515df → 0.16.0-alpha.0-20250920-809524dba

package/dist/esm/bdx/BdxProtocol.js

@@ -0,0 +1,82 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Logger, MatterError } from "#general";
+import { BDX_PROTOCOL_ID, BdxMessageType, BdxStatusCode } from "#types";
+import { BdxMessenger } from "./BdxMessenger.js";
+import { BdxSession } from "./BdxSession.js";
+import { BdxInitMessageSchema } from "./schema/BdxInitMessagesSchema.js";
+const logger = Logger.get("BdxProtocol");
+class BdxProtocol {
+  id = BDX_PROTOCOL_ID;
+  requiresSecureSession = true;
+  #activeBdxSessions = /* @__PURE__ */ new Map();
+  #storage;
+  #bdxLimits;
+  /**
+   * Create a new BDX protocol handler.
+   * @param storage StorageContext to read or write files from/to.
+   * @param options BDX options/limits to use for this session. us this to control how the transfer should behave.
+   */
+  constructor(storage, options) {
+    this.#storage = storage;
+    this.#bdxLimits = options;
+  }
+  async onNewExchange(exchange, message) {
+    const initMessageType = message.payloadHeader.messageType;
+    const messenger = new BdxMessenger(exchange);
+    switch (initMessageType) {
+      case BdxMessageType.SendInit:
+      case BdxMessageType.ReceiveInit:
+        logger.debug(
+          `Initialize Session for ${BdxMessageType[initMessageType]} message on BDX protocol for exchange ${exchange.id}`
+        );
+        const { payload } = message;
+        const bdxSession = BdxSession.fromMessage(this.#storage, messenger, {
+          initMessageType,
+          initMessage: new BdxInitMessageSchema().decode(payload),
+          ...this.#bdxLimits
+        });
+        await this.#registerSession(messenger, bdxSession);
+        try {
+          await bdxSession.processTransfer();
+        } catch (error) {
+          logger.error(`Error processing BDX transfer:`, error);
+        }
+        break;
+      default:
+        logger.warn(
+          `Unexpected BDX message type ${BdxMessageType[initMessageType]} on new exchange ${exchange.id}`
+        );
+        await messenger.sendError(BdxStatusCode.UnexpectedMessage);
+    }
+  }
+  /** Make sure only one BDX session can be active per exchange and that the exchange is closed with the BDX session. */
+  async #registerSession(messenger, bdxSession) {
+    const exchange = messenger.exchange;
+    if (this.#activeBdxSessions.has(exchange)) {
+      logger.warn(`BDX session for exchange ${exchange.id} already exists, sending error`);
+      await messenger.sendError(BdxStatusCode.UnexpectedMessage);
+      return;
+    }
+    this.#activeBdxSessions.set(exchange, bdxSession);
+    bdxSession.closed.on(async () => {
+      logger.debug(`BDX session for exchange ${exchange.id} closed`);
+      this.#activeBdxSessions.delete(exchange);
+      await exchange.close();
+    });
+  }
+  async close() {
+    logger.debug(`Closing BDX protocol handler with ${this.#activeBdxSessions.size} active sessions`);
+    for (const session of this.#activeBdxSessions.values()) {
+      await session.close(new MatterError("BDX protocol handler closed"));
+    }
+    this.#activeBdxSessions.clear();
+  }
+}
+export {
+  BdxProtocol
+};
+//# sourceMappingURL=BdxProtocol.js.map

package/dist/esm/bdx/BdxProtocol.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../../src/bdx/BdxProtocol.ts"],
+  "mappings": "AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,SAAS,QAAQ,mBAAmC;AAGpD,SAAS,iBAAiB,gBAAgB,qBAAqB;AAE/D,SAAS,oBAAoB;AAC7B,SAAS,kBAAkB;AAE3B,SAAS,4BAA4B;AAErC,MAAM,SAAS,OAAO,IAAI,aAAa;AAGhC,MAAM,YAAuC;AAAA,EACvC,KAAK;AAAA,EACL,wBAAwB;AAAA,EACxB,qBAAqB,oBAAI,IAAiC;AAAA,EACnE;AAAA,EACA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,YAAY,SAAyB,SAA0C;AAC3E,SAAK,WAAW;AAChB,SAAK,aAAa;AAAA,EACtB;AAAA,EAEA,MAAM,cAAc,UAA2B,SAAkB;AAC7D,UAAM,kBAAkB,QAAQ,cAAc;AAC9C,UAAM,YAAY,IAAI,aAAa,QAAQ;AAE3C,YAAQ,iBAAiB;AAAA,MACrB,KAAK,eAAe;AAAA,MACpB,KAAK,eAAe;AAChB,eAAO;AAAA,UACH,0BAA0B,eAAe,eAAe,CAAC,yCAAyC,SAAS,EAAE;AAAA,QACjH;AACA,cAAM,EAAE,QAAQ,IAAI;AACpB,cAAM,aAAa,WAAW,YAAY,KAAK,UAAU,WAAW;AAAA,UAChE;AAAA,UACA,aAAa,IAAI,qBAAqB,EAAE,OAAO,OAAO;AAAA,UACtD,GAAG,KAAK;AAAA,QACZ,CAAC;AACD,cAAM,KAAK,iBAAiB,WAAW,UAAU;AAEjD,YAAI;AACA,gBAAM,WAAW,gBAAgB;AAAA,QACrC,SAAS,OAAO;AACZ,iBAAO,MAAM,kCAAkC,KAAK;AAAA,QACxD;AAEA;AAAA,MACJ;AACI,eAAO;AAAA,UACH,+BAA+B,eAAe,eAAe,CAAC,oBAAoB,SAAS,EAAE;AAAA,QACjG;AACA,cAAM,UAAU,UAAU,cAAc,iBAAiB;AAAA,IACjE;AAAA,EACJ;AAAA;AAAA,EAGA,MAAM,iBAAiB,WAAyB,YAAwB;AACpE,UAAM,WAAW,UAAU;AAC3B,QAAI,KAAK,mBAAmB,IAAI,QAAQ,GAAG;AACvC,aAAO,KAAK,4BAA4B,SAAS,EAAE,gCAAgC;AACnF,YAAM,UAAU,UAAU,cAAc,iBAAiB;AACzD;AAAA,IACJ;AACA,SAAK,mBAAmB,IAAI,UAAU,UAAU;AAChD,eAAW,OAAO,GAAG,YAAY;AAC7B,aAAO,MAAM,4BAA4B,SAAS,EAAE,SAAS;AAC7D,WAAK,mBAAmB,OAAO,QAAQ;AACvC,YAAM,SAAS,MAAM;AAAA,IACzB,CAAC;AAAA,EACL;AAAA,EAEA,MAAM,QAAQ;AACV,WAAO,MAAM,qCAAqC,KAAK,mBAAmB,IAAI,kBAAkB;AAChG,eAAW,WAAW,KAAK,mBAAmB,OAAO,GAAG;AACpD,YAAM,QAAQ,MAAM,IAAI,YAAY,6BAA6B,CAAC;AAAA,IACtE;AACA,SAAK,mBAAmB,MAAM;AAAA,EAClC;AACJ;",
+  "names": []
+}

package/dist/esm/bdx/BdxSession.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { AsyncObservable, StorageContext } from "#general";
+import { BdxMessenger } from "./BdxMessenger.js";
+import { BdxSessionConfiguration } from "./BdxSessionConfiguration.js";
+/**
+ * Class to manage one BDX session.
+ *
+ * Matter BDX protocol is used to transfer files between devices.
+ *
+ * Notes:
+ * * Even though Matter allows 64bit values for size and offset, we do not use them, as they make no sense for now.
+ *   We support up to MAX_SAFE_INTEGER for size and offset (which basically is 2^53 - 1 and so far enough for us).
+ * * We support partial transfers (startOffset or shorter dataLength) only when we act as the sender. As a receiver,
+ *   only full transfers are supported.
+ * * We do not use BlockQueryWithSkip when requesting data ourselves
+ */
+export declare class BdxSession {
+    #private;
+    /** Initializes a BdxSession as a sender, means that we upload data to the peer. */
+    static asSender(messenger: BdxMessenger, options: BdxSessionConfiguration.SenderInitiatorOptions): BdxSession;
+    /** Initializes a BdxSession as a receiver, means that we download data from the peer. */
+    static asReceiver(messenger: BdxMessenger, options: BdxSessionConfiguration.InitiatorOptions): BdxSession;
+    /** Initializes a BdxSession from an incoming *Init message. The message determines the direction of the transfer. */
+    static fromMessage(storage: StorageContext, messenger: BdxMessenger, options: BdxSessionConfiguration.ReceiverOptions): BdxSession;
+    private constructor();
+    /** Method called to start the session. It will end with a successful Transfer or with an error */
+    processTransfer(): Promise<void>;
+    get closed(): AsyncObservable<any[], void>;
+    close(error?: unknown): Promise<void>;
+}
+export declare namespace BdxSession { }
+//# sourceMappingURL=BdxSession.d.ts.map

package/dist/esm/bdx/BdxSession.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BdxSession.d.ts","sourceRoot":"","sources":["../../../src/bdx/BdxSession.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,eAAe,EAAoC,cAAc,EAAE,MAAM,UAAU,CAAC;AAI7F,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAUvE;;;;;;;;;;;GAWG;AACH,qBAAa,UAAU;;IAUnB,mFAAmF;IACnF,MAAM,CAAC,QAAQ,CAAC,SAAS,EAAE,YAAY,EAAE,OAAO,EAAE,uBAAuB,CAAC,sBAAsB,GAAG,UAAU;IAI7G,yFAAyF;IACzF,MAAM,CAAC,UAAU,CAAC,SAAS,EAAE,YAAY,EAAE,OAAO,EAAE,uBAAuB,CAAC,gBAAgB,GAAG,UAAU;IAIzG,qHAAqH;IACrH,MAAM,CAAC,WAAW,CACd,OAAO,EAAE,cAAc,EACvB,SAAS,EAAE,YAAY,EACvB,OAAO,EAAE,uBAAuB,CAAC,eAAe,GACjD,UAAU;IAkBb,OAAO;IAeP,kGAAkG;IAC5F,eAAe;IAmErB,IAAI,MAAM,iCAET;IAEK,KAAK,CAAC,KAAK,CAAC,EAAE,OAAO;CAQ9B;AAED,yBAAiB,UAAU,CAAC,GAAE"}

package/dist/esm/bdx/BdxSession.js

@@ -0,0 +1,133 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { AsyncObservable, Diagnostic, Logger } from "#general";
+import { BdxMessageType, BdxStatusCode } from "#types";
+import { bdxSessionInitiator } from "./bdx-session-initiator.js";
+import { BdxError } from "./BdxError.js";
+import { BdxSessionConfiguration } from "./BdxSessionConfiguration.js";
+import { DrivenSendingFlow } from "./flow/DrivenSendingFlow.js";
+import { DrivingReceivingFlow } from "./flow/DrivingReceivingFlow.js";
+import { Flow } from "./flow/Flow.js";
+import { FollowingReceivingFlow } from "./flow/FollowingReceivingFlow.js";
+import { FollowingSendingFlow } from "./flow/FollowingSendingFlow.js";
+import { PersistedFileDesignator } from "./PersistedFileDesignator.js";
+const logger = Logger.get("BdxSession");
+class BdxSession {
+  #messenger;
+  #started = false;
+  #closed = AsyncObservable();
+  #isClosed = false;
+  #config;
+  #transferFlow;
+  /** Initializes a BdxSession as a sender, means that we upload data to the peer. */
+  static asSender(messenger, options) {
+    return new BdxSession(messenger, { isSender: true, ...options });
+  }
+  /** Initializes a BdxSession as a receiver, means that we download data from the peer. */
+  static asReceiver(messenger, options) {
+    return new BdxSession(messenger, { isSender: false, ...options });
+  }
+  /** Initializes a BdxSession from an incoming *Init message. The message determines the direction of the transfer. */
+  static fromMessage(storage, messenger, options) {
+    const { initMessageType, initMessage } = options;
+    if (initMessageType !== BdxMessageType.SendInit && initMessageType !== BdxMessageType.ReceiveInit) {
+      throw new BdxError(
+        `Invalid message type for BDX session initialization: ${BdxMessageType[initMessageType]} (${initMessageType})`,
+        BdxStatusCode.UnexpectedMessage
+      );
+    }
+    const { fileDesignator } = initMessage;
+    return new BdxSession(messenger, {
+      isSender: initMessageType === BdxMessageType.ReceiveInit,
+      fileDesignator: new PersistedFileDesignator(fileDesignator, storage),
+      ...options
+    });
+  }
+  constructor(messenger, options) {
+    this.#messenger = messenger;
+    this.#config = new BdxSessionConfiguration(options);
+    const exchange = messenger.exchange;
+    if (!exchange.channel.isReliable) {
+      throw new BdxError("Bdx Protocol requires a reliable channel for message exchange");
+    }
+    exchange.closed.on(async () => {
+      logger.debug(`Closing BDX session for exchange ${exchange.id}`);
+      await this.close();
+    });
+  }
+  /** Method called to start the session. It will end with a successful Transfer or with an error */
+  async processTransfer() {
+    if (this.#started) {
+      throw new BdxError("BDX session already started", BdxStatusCode.UnexpectedMessage);
+    }
+    if (this.#isClosed) {
+      throw new BdxError("BDX session already closed", BdxStatusCode.UnexpectedMessage);
+    }
+    const { isSender, isInitiator, fileDesignator } = this.#config;
+    logger.info(
+      `Starting BDX session`,
+      Diagnostic.dict({
+        exId: this.#messenger.exchange.id,
+        isSender,
+        isInitiator,
+        blobName: fileDesignator?.text
+      })
+    );
+    this.#started = true;
+    try {
+      this.#transferFlow = this.#initializeFlow(await bdxSessionInitiator(this.#messenger, this.#config));
+      await this.#transferFlow.processTransfer();
+      await this.close();
+    } catch (error) {
+      BdxError.accept(error);
+      await this.#messenger.sendError(error.code);
+      logger.warn(`BDX session failed with error:`, error);
+      await this.close(error);
+      throw error;
+    }
+  }
+  #initializeFlow(transferParameters) {
+    const { transferMode, asynchronousTransfer, dataLength, isDriver, fileDesignator } = transferParameters;
+    const isSenderDrive = transferMode === Flow.DriverMode.SenderDrive;
+    const role = `${isSenderDrive ? `${asynchronousTransfer ? "async " : ""}sending` : "receiving"} ${isDriver ? "driver" : "follower"}`;
+    logger.debug(
+      `Starting transfer flow as ${role}`,
+      Diagnostic.dict({
+        exId: this.#messenger.exchange.id,
+        dataLength,
+        blobName: fileDesignator.text
+      })
+    );
+    let FlowImpl;
+    if (isDriver) {
+      if (isSenderDrive || asynchronousTransfer) {
+        FlowImpl = DrivenSendingFlow;
+      } else {
+        FlowImpl = DrivingReceivingFlow;
+      }
+    } else if (isSenderDrive || asynchronousTransfer) {
+      FlowImpl = FollowingSendingFlow;
+    } else {
+      FlowImpl = FollowingReceivingFlow;
+    }
+    return new FlowImpl(this.#messenger, transferParameters);
+  }
+  get closed() {
+    return this.#closed;
+  }
+  async close(error) {
+    if (this.#isClosed) {
+      return;
+    }
+    this.#isClosed = true;
+    await this.#transferFlow?.close(error);
+    await this.#closed.emit();
+  }
+}
+export {
+  BdxSession
+};
+//# sourceMappingURL=BdxSession.js.map

package/dist/esm/bdx/BdxSession.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../../src/bdx/BdxSession.ts"],
+  "mappings": "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",
+  "names": []
+}

package/dist/esm/bdx/BdxSessionConfiguration.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { BdxMessageType } from "#types";
+import { Flow } from "./flow/Flow.js";
+import { PersistedFileDesignator } from "./PersistedFileDesignator.js";
+import { BdxInit } from "./schema/BdxInitMessagesSchema.js";
+export declare class BdxSessionConfiguration {
+    #private;
+    constructor(options: BdxSessionConfiguration.Options);
+    get isSender(): boolean;
+    get initMessage(): BdxInit | undefined;
+    get isInitiator(): boolean;
+    get fileDesignator(): PersistedFileDesignator;
+    get transferConfig(): BdxSessionConfiguration.Config;
+}
+export declare namespace BdxSessionConfiguration {
+    interface Config {
+        /**
+         * Array of preferred transfer driver modes, in order of preference. Use this to configure the proposed behavior.
+         * Default is [SenderDrive, ReceiverDrive]
+         */
+        preferredDriverModes?: Flow.DriverMode[];
+        /** Asynchronous transfer is not supported right now because provisional. */
+        asynchronousTransferAllowed?: false;
+        /** Maximum block size to use for the session. This value is ignored if the transport only supports smaller blocks. */
+        maxBlockSize?: number;
+        /** Maximum transfer size to use for the session. Defaults to 100MB */
+        maxTransferSize?: number;
+        /** The start offset of the data to send. When using this, you need to know what you are doing. */
+        senderStartOffset?: number;
+        /** The maximum length of the data to send. When using this, you need to know what you are doing. */
+        senderMaxLength?: number;
+    }
+    const DefaultConfig: BdxSessionConfiguration.Config;
+    interface InitiatorOptions extends BdxSessionConfiguration.Config {
+        /** FileDesignator to use for the session. The value is usually pre-determined with the peer. */
+        fileDesignator: PersistedFileDesignator;
+    }
+    interface SenderInitiatorOptions extends InitiatorOptions {
+        /** The start offset of the data to send. When using this, you need to know what you are doing. */
+        senderStartOffset?: number;
+        /** The maximum length of the data to send. When using this, you need to know what you are doing. */
+        senderMaxLength?: number;
+    }
+    interface ReceiverOptions extends BdxSessionConfiguration.Config {
+        initMessageType: BdxMessageType;
+        initMessage: BdxInit;
+    }
+    interface Options extends BdxSessionConfiguration.Config {
+        /** True if the session is initiated as a sender, false for receiver */
+        isSender: boolean;
+        /** File designator to use for the session */
+        fileDesignator: PersistedFileDesignator;
+        /** The initial message received to start the session */
+        initMessage?: BdxInit;
+    }
+}
+//# sourceMappingURL=BdxSessionConfiguration.d.ts.map

package/dist/esm/bdx/BdxSessionConfiguration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BdxSessionConfiguration.d.ts","sourceRoot":"","sources":["../../../src/bdx/BdxSessionConfiguration.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AACxC,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AACvE,OAAO,EAAE,OAAO,EAAE,MAAM,mCAAmC,CAAC;AAE5D,qBAAa,uBAAuB;;gBAMpB,OAAO,EAAE,uBAAuB,CAAC,OAAO;IAiCpD,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,IAAI,WAAW,IAAI,OAAO,GAAG,SAAS,CAErC;IAED,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,IAAI,cAAc,IAAI,uBAAuB,CAE5C;IAED,IAAI,cAAc,IAAI,uBAAuB,CAAC,MAAM,CAEnD;CACJ;AAED,yBAAiB,uBAAuB,CAAC;IACrC,UAAiB,MAAM;QACnB;;;WAGG;QACH,oBAAoB,CAAC,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC;QAEzC,4EAA4E;QAC5E,2BAA2B,CAAC,EAAE,KAAK,CAAC;QAEpC,sHAAsH;QACtH,YAAY,CAAC,EAAE,MAAM,CAAC;QAEtB,sEAAsE;QACtE,eAAe,CAAC,EAAE,MAAM,CAAC;QAEzB,kGAAkG;QAClG,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAE3B,oGAAoG;QACpG,eAAe,CAAC,EAAE,MAAM,CAAC;KAC5B;IAEM,MAAM,aAAa,EAAE,uBAAuB,CAAC,MAOnD,CAAC;IAEF,UAAiB,gBAAiB,SAAQ,uBAAuB,CAAC,MAAM;QACpE,gGAAgG;QAChG,cAAc,EAAE,uBAAuB,CAAC;KAC3C;IAED,UAAiB,sBAAuB,SAAQ,gBAAgB;QAC5D,kGAAkG;QAClG,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAE3B,oGAAoG;QACpG,eAAe,CAAC,EAAE,MAAM,CAAC;KAC5B;IAED,UAAiB,eAAgB,SAAQ,uBAAuB,CAAC,MAAM;QACnE,eAAe,EAAE,cAAc,CAAC;QAChC,WAAW,EAAE,OAAO,CAAC;KACxB;IAED,UAAiB,OAAQ,SAAQ,uBAAuB,CAAC,MAAM;QAC3D,uEAAuE;QACvE,QAAQ,EAAE,OAAO,CAAC;QAElB,6CAA6C;QAC7C,cAAc,EAAE,uBAAuB,CAAC;QAExC,wDAAwD;QACxD,WAAW,CAAC,EAAE,OAAO,CAAC;KACzB;CACJ"}

package/dist/esm/bdx/BdxSessionConfiguration.js

@@ -0,0 +1,75 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ImplementationError } from "#general";
+import { Flow } from "./flow/Flow.js";
+class BdxSessionConfiguration {
+  #isSender;
+  #initMessage;
+  #transferConfig;
+  #fileDesignator;
+  constructor(options) {
+    const { isSender, fileDesignator, initMessage } = options;
+    this.#fileDesignator = fileDesignator;
+    this.#isSender = isSender;
+    this.#initMessage = initMessage;
+    this.#transferConfig = { ...BdxSessionConfiguration.DefaultConfig, ...options };
+    const {
+      preferredDriverModes = [],
+      maxBlockSize,
+      maxTransferSize,
+      asynchronousTransferAllowed,
+      senderStartOffset,
+      senderMaxLength
+    } = this.#transferConfig;
+    if (preferredDriverModes.length === 0) {
+      throw new ImplementationError("At least one preferred driver mode must be set.");
+    }
+    if (maxBlockSize !== void 0 && maxBlockSize <= 0) {
+      throw new ImplementationError("Max block size must be greater than 0");
+    }
+    if (maxTransferSize !== void 0 && maxTransferSize <= 0) {
+      throw new ImplementationError("Max transfer size must be greater than 0");
+    }
+    if (asynchronousTransferAllowed) {
+      throw new ImplementationError("Asynchronous transfer is not supported");
+    }
+    if (!isSender && (senderStartOffset !== void 0 || senderMaxLength !== void 0)) {
+      throw new ImplementationError("Sender start offset and sender max length are only supported for senders");
+    }
+  }
+  get isSender() {
+    return this.#isSender;
+  }
+  get initMessage() {
+    return this.#initMessage;
+  }
+  get isInitiator() {
+    return this.#initMessage === void 0;
+  }
+  get fileDesignator() {
+    return this.#fileDesignator;
+  }
+  get transferConfig() {
+    return this.#transferConfig;
+  }
+}
+((BdxSessionConfiguration2) => {
+  BdxSessionConfiguration2.DefaultConfig = {
+    preferredDriverModes: [
+      Flow.DriverMode.SenderDrive,
+      // Default if multiple is supported, so lets use this
+      Flow.DriverMode.ReceiverDrive
+    ],
+    asynchronousTransferAllowed: false,
+    // Provisional, not supported
+    maxTransferSize: 1024 * 1e5
+    // 100 MB, lets use that as maximum transfer filesize for now just to protect
+  };
+})(BdxSessionConfiguration || (BdxSessionConfiguration = {}));
+export {
+  BdxSessionConfiguration
+};
+//# sourceMappingURL=BdxSessionConfiguration.js.map

package/dist/esm/bdx/BdxSessionConfiguration.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../../src/bdx/BdxSessionConfiguration.ts"],
+  "mappings": "AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,SAAS,2BAA2B;AAEpC,SAAS,YAAY;AAId,MAAM,wBAAwB;AAAA,EACjC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAEA,YAAY,SAA0C;AAClD,UAAM,EAAE,UAAU,gBAAgB,YAAY,IAAI;AAClD,SAAK,kBAAkB;AACvB,SAAK,YAAY;AACjB,SAAK,eAAe;AACpB,SAAK,kBAAkB,EAAE,GAAG,wBAAwB,eAAe,GAAG,QAAQ;AAG9E,UAAM;AAAA,MACF,uBAAuB,CAAC;AAAA,MACxB;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACJ,IAAI,KAAK;AACT,QAAI,qBAAqB,WAAW,GAAG;AACnC,YAAM,IAAI,oBAAoB,iDAAiD;AAAA,IACnF;AACA,QAAI,iBAAiB,UAAa,gBAAgB,GAAG;AACjD,YAAM,IAAI,oBAAoB,uCAAuC;AAAA,IACzE;AACA,QAAI,oBAAoB,UAAa,mBAAmB,GAAG;AACvD,YAAM,IAAI,oBAAoB,0CAA0C;AAAA,IAC5E;AACA,QAAI,6BAA6B;AAC7B,YAAM,IAAI,oBAAoB,wCAAwC;AAAA,IAC1E;AACA,QAAI,CAAC,aAAa,sBAAsB,UAAa,oBAAoB,SAAY;AACjF,YAAM,IAAI,oBAAoB,0EAA0E;AAAA,IAC5G;AAAA,EACJ;AAAA,EAEA,IAAI,WAAoB;AACpB,WAAO,KAAK;AAAA,EAChB;AAAA,EAEA,IAAI,cAAmC;AACnC,WAAO,KAAK;AAAA,EAChB;AAAA,EAEA,IAAI,cAAuB;AACvB,WAAO,KAAK,iBAAiB;AAAA,EACjC;AAAA,EAEA,IAAI,iBAA0C;AAC1C,WAAO,KAAK;AAAA,EAChB;AAAA,EAEA,IAAI,iBAAiD;AACjD,WAAO,KAAK;AAAA,EAChB;AACJ;AAAA,CAEO,CAAUA,6BAAV;AAwBI,EAAMA,yBAAA,gBAAgD;AAAA,IACzD,sBAAsB;AAAA,MAClB,KAAK,WAAW;AAAA;AAAA,MAChB,KAAK,WAAW;AAAA,IACpB;AAAA,IACA,6BAA6B;AAAA;AAAA,IAC7B,iBAAiB,OAAQ;AAAA;AAAA,EAC7B;AAAA,GA/Ba;",
+  "names": ["BdxSessionConfiguration"]
+}

package/dist/esm/bdx/FileDesignator.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Bytes } from "#general";
+/**
+ * Class to represent a File designator from Matter.
+ * Specification wise this is a bytes object, but to store in a storage we need a string name.
+ * This class provides a way to convert between the two.
+ */
+export declare class FileDesignator {
+    #private;
+    /** Create a FileDesignator from a string or bytes object. */
+    constructor(fd: string | Bytes);
+    /** Return the bytes representation of the FileDesignator. */
+    get bytes(): Bytes;
+    /** Return the textual/string representation of the FileDesignator. */
+    get text(): string;
+}
+//# sourceMappingURL=FileDesignator.d.ts.map

package/dist/esm/bdx/FileDesignator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileDesignator.d.ts","sourceRoot":"","sources":["../../../src/bdx/FileDesignator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAEjC;;;;GAIG;AACH,qBAAa,cAAc;;IAGvB,6DAA6D;gBACjD,EAAE,EAAE,MAAM,GAAG,KAAK;IAQ9B,6DAA6D;IAC7D,IAAI,KAAK,IAAI,KAAK,CAEjB;IAED,sEAAsE;IACtE,IAAI,IAAI,IAAI,MAAM,CAgBjB;CACJ"}

package/dist/esm/bdx/FileDesignator.js

@@ -0,0 +1,42 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Bytes } from "#general";
+class FileDesignator {
+  #fd;
+  /** Create a FileDesignator from a string or bytes object. */
+  constructor(fd) {
+    if (typeof fd === "string") {
+      this.#fd = Bytes.fromString(fd);
+    } else {
+      this.#fd = fd;
+    }
+  }
+  /** Return the bytes representation of the FileDesignator. */
+  get bytes() {
+    return this.#fd;
+  }
+  /** Return the textual/string representation of the FileDesignator. */
+  get text() {
+    const fileDesignatorData = Bytes.of(this.#fd);
+    const isValidName = fileDesignatorData.every(
+      (byte) => byte >= 65 && byte <= 90 || // A-Z
+      byte >= 97 && byte <= 122 || // a-z
+      byte >= 48 && byte <= 57 || // 0..9
+      byte === 46 || // "."
+      byte === 45
+      // "-"
+    );
+    if (isValidName) {
+      return fileDesignatorData.reduce((name, byte) => name + String.fromCharCode(byte), "");
+    } else {
+      return `0x${Bytes.toHex(fileDesignatorData)}`;
+    }
+  }
+}
+export {
+  FileDesignator
+};
+//# sourceMappingURL=FileDesignator.js.map

package/dist/esm/bdx/FileDesignator.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../../src/bdx/FileDesignator.ts"],
+  "mappings": "AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,SAAS,aAAa;AAOf,MAAM,eAAe;AAAA,EACxB;AAAA;AAAA,EAGA,YAAY,IAAoB;AAC5B,QAAI,OAAO,OAAO,UAAU;AACxB,WAAK,MAAM,MAAM,WAAW,EAAE;AAAA,IAClC,OAAO;AACH,WAAK,MAAM;AAAA,IACf;AAAA,EACJ;AAAA;AAAA,EAGA,IAAI,QAAe;AACf,WAAO,KAAK;AAAA,EAChB;AAAA;AAAA,EAGA,IAAI,OAAe;AACf,UAAM,qBAAqB,MAAM,GAAG,KAAK,GAAG;AAE5C,UAAM,cAAc,mBAAmB;AAAA,MACnC,UACK,QAAQ,MAAQ,QAAQ;AAAA,MACxB,QAAQ,MAAQ,QAAQ;AAAA,MACxB,QAAQ,MAAQ,QAAQ;AAAA,MACzB,SAAS;AAAA,MACT,SAAS;AAAA;AAAA,IACjB;AACA,QAAI,aAAa;AACb,aAAO,mBAAmB,OAAO,CAAC,MAAM,SAAS,OAAO,OAAO,aAAa,IAAI,GAAG,EAAE;AAAA,IACzF,OAAO;AACH,aAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAAA,IAC/C;AAAA,EACJ;AACJ;",
+  "names": []
+}

package/dist/esm/bdx/PersistedFileDesignator.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Bytes, StorageContext } from "#general";
+import { FileDesignator } from "./FileDesignator.js";
+/** A FileDesignator that points to a persisted file in a given StorageContext. */
+export declare class PersistedFileDesignator extends FileDesignator {
+    #private;
+    constructor(fd: string | Bytes, storage: StorageContext);
+    exists(): import("#general").MaybePromise<boolean>;
+    openBlob(): Promise<Blob>;
+    writeFromStream(stream: ReadableStream<Bytes>): import("#general").MaybePromise<void>;
+}
+//# sourceMappingURL=PersistedFileDesignator.d.ts.map

package/dist/esm/bdx/PersistedFileDesignator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PersistedFileDesignator.d.ts","sourceRoot":"","sources":["../../../src/bdx/PersistedFileDesignator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,EAAuB,cAAc,EAAE,MAAM,UAAU,CAAC;AACtE,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,kFAAkF;AAClF,qBAAa,uBAAwB,SAAQ,cAAc;;gBAI3C,EAAE,EAAE,MAAM,GAAG,KAAK,EAAE,OAAO,EAAE,cAAc;IAKvD,MAAM;IAIA,QAAQ;IAad,eAAe,CAAC,MAAM,EAAE,cAAc,CAAC,KAAK,CAAC;CAGhD"}

package/dist/esm/bdx/PersistedFileDesignator.js

@@ -0,0 +1,37 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ImplementationError } from "#general";
+import { FileDesignator } from "./FileDesignator.js";
+class PersistedFileDesignator extends FileDesignator {
+  #storage;
+  #blob;
+  constructor(fd, storage) {
+    super(fd);
+    this.#storage = storage;
+  }
+  exists() {
+    return this.#storage.has(this.text);
+  }
+  async openBlob() {
+    if (this.#blob === void 0) {
+      const blobName = this.text;
+      if (!this.#storage.has(blobName)) {
+        throw new ImplementationError(
+          "File designator must point to an existing file in the storage to send data"
+        );
+      }
+      this.#blob = await this.#storage.openBlob(blobName);
+    }
+    return this.#blob;
+  }
+  writeFromStream(stream) {
+    return this.#storage.writeBlobFromStream(this.text, stream);
+  }
+}
+export {
+  PersistedFileDesignator
+};
+//# sourceMappingURL=PersistedFileDesignator.js.map

package/dist/esm/bdx/PersistedFileDesignator.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../../src/bdx/PersistedFileDesignator.ts"],
+  "mappings": "AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,SAAgB,2BAA2C;AAC3D,SAAS,sBAAsB;AAGxB,MAAM,gCAAgC,eAAe;AAAA,EACxD;AAAA,EACA;AAAA,EAEA,YAAY,IAAoB,SAAyB;AACrD,UAAM,EAAE;AACR,SAAK,WAAW;AAAA,EACpB;AAAA,EAEA,SAAS;AACL,WAAO,KAAK,SAAS,IAAI,KAAK,IAAI;AAAA,EACtC;AAAA,EAEA,MAAM,WAAW;AACb,QAAI,KAAK,UAAU,QAAW;AAC1B,YAAM,WAAW,KAAK;AACtB,UAAI,CAAC,KAAK,SAAS,IAAI,QAAQ,GAAG;AAC9B,cAAM,IAAI;AAAA,UACN;AAAA,QACJ;AAAA,MACJ;AACA,WAAK,QAAQ,MAAM,KAAK,SAAS,SAAS,QAAQ;AAAA,IACtD;AACA,WAAO,KAAK;AAAA,EAChB;AAAA,EAEA,gBAAgB,QAA+B;AAC3C,WAAO,KAAK,SAAS,oBAAoB,KAAK,MAAM,MAAM;AAAA,EAC9D;AACJ;",
+  "names": []
+}

package/dist/esm/bdx/bdx-session-initiator.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { BdxMessenger } from "./BdxMessenger.js";
+import { BdxSessionConfiguration } from "./BdxSessionConfiguration.js";
+import { Flow } from "./flow/Flow.js";
+/**
+ * Handles the initiation of a BDX session by exchanging *Init and *Accept messages and negotiating the transfer
+ * parameters.
+ */
+export declare function bdxSessionInitiator(messenger: BdxMessenger, config: BdxSessionConfiguration): Promise<Flow.TransferOptions>;
+//# sourceMappingURL=bdx-session-initiator.d.ts.map

package/dist/esm/bdx/bdx-session-initiator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bdx-session-initiator.d.ts","sourceRoot":"","sources":["../../../src/bdx/bdx-session-initiator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AACvE,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAMtC;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,uBAAuB,iCAgOjG"}