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

package/src/bdx/BdxMessenger.ts

@@ -0,0 +1,291 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Message } from "#codec/MessageCodec.js";
+import {
+    Bytes,
+    Diagnostic,
+    Duration,
+    ImplementationError,
+    InternalError,
+    Logger,
+    Minutes,
+    UnexpectedDataError,
+} from "#general";
+import { MessageExchange } from "#protocol/MessageExchange.js";
+import { BdxMessageType, BdxStatusCode, GeneralStatusCode, SecureMessageType } from "#types";
+import { BdxError, BdxStatusResponseError } from "./BdxError.js";
+import { BdxReceiveAccept, BdxSendAccept } from "./schema/BdxAcceptMessagesSchema.js";
+import {
+    BdxBlock,
+    BdxBlockAck,
+    BdxBlockAckEof,
+    BdxBlockEof,
+    BdxBlockQuery,
+    BdxBlockQueryWithSkip,
+} from "./schema/BdxBlockMessagesSchema.js";
+import { BdxInit } from "./schema/BdxInitMessagesSchema.js";
+import { BdxMessage } from "./schema/BdxMessage.js";
+import { BdxStatusMessage } from "./schema/BdxStatusMessageSchema.js";
+
+const logger = Logger.get("BdxMessenger");
+
+export const BDX_TRANSFER_IDLE_TIMEOUT = Minutes(5); // Minimum time according to Matter spec
+
+/** Messenger class that contains all Bdx Messages */
+export class BdxMessenger {
+    #exchange: MessageExchange;
+    #messageTimeout: Duration;
+
+    /**
+     * Creates a new BdxMessenger instance.
+     * @param exchange Exchange to use for the messaging
+     * @param messageTimeout Communication Timeout for the Bdx Messages, defaults to 5 minutes as defined for Matter OTA transfers
+     */
+    constructor(exchange: MessageExchange, messageTimeout = BDX_TRANSFER_IDLE_TIMEOUT) {
+        if (!exchange.channel.isReliable) {
+            throw new ImplementationError("Bdx Protocol requires a reliable channel for message exchange");
+        }
+        this.#messageTimeout = messageTimeout;
+        this.#exchange = exchange;
+    }
+
+    get channel() {
+        return this.#exchange.channel;
+    }
+
+    get exchange() {
+        return this.#exchange;
+    }
+
+    get maxPayloadSize() {
+        return this.#exchange.maxPayloadSize;
+    }
+
+    /**
+     * Waits for the next message and returns it.
+     * A List of allowed expected message types can be provided.
+     * If the message type is not in the list, an error will be thrown.
+     */
+    async nextMessage(
+        expectedMessageTypes: BdxMessageType[],
+        timeout = this.#messageTimeout,
+        expectedMessageInfo?: string,
+    ): Promise<BdxMessage<any>> {
+        logger.debug(
+            `Waiting for Bdx ${expectedMessageTypes.map(t => BdxMessageType[t]).join("/")} message with timeout ${timeout}ms`,
+        );
+
+        const message = await this.exchange.nextMessage({ timeout });
+        const messageType = message.payloadHeader.messageType as BdxMessageType;
+        if (expectedMessageInfo === undefined) {
+            expectedMessageInfo = expectedMessageTypes.map(t => `${t} (${BdxMessageType[t]})`).join(",");
+        }
+        this.throwIfErrorStatusReport(message, expectedMessageInfo);
+        if (!expectedMessageTypes.includes(messageType))
+            throw new UnexpectedDataError(
+                `Received unexpected message type: ${BdxMessageType[messageType] ?? "unknown"}#${messageType}, expected: ${expectedMessageInfo}`,
+            );
+
+        logger.debug(
+            `Received Bdx ${BdxMessageType[messageType]}${message.payload.byteLength > 0 ? ` with ${message.payload.byteLength}bytes` : ""}`,
+            message,
+        );
+        return BdxMessage.decode(messageType, message.payload);
+    }
+
+    async send(bdxMessage: BdxMessage<any>) {
+        const { kind: messageType, message } = bdxMessage;
+        logger.debug(
+            `Sending Bdx ${BdxMessageType[messageType]}${"data" in message && Bytes.isBytes(message.data) ? ` with ${message.data.byteLength}bytes` : ""}`,
+            message,
+        );
+        await this.exchange.send(messageType, BdxMessage.encode(bdxMessage));
+    }
+
+    /** Sends a Bdx SendInit message and waits for the SendAccept message as a response and returns it decoded. */
+    async sendSendInit(message: BdxInit): Promise<BdxSendAccept> {
+        await this.send({ kind: BdxMessageType.SendInit, message });
+
+        const response = await this.nextMessage([BdxMessageType.SendAccept]);
+        BdxMessage.assert(response, BdxMessageType.SendAccept);
+        return response.message;
+    }
+
+    /** Sends a ReceiveInit message and waits for the ReceiveAccept message as a response and returns it decoded. */
+    async sendReceiveInit(message: BdxInit): Promise<BdxReceiveAccept> {
+        await this.send({ kind: BdxMessageType.ReceiveInit, message });
+
+        const response = await this.nextMessage([BdxMessageType.ReceiveAccept]);
+        BdxMessage.assert(response, BdxMessageType.ReceiveAccept);
+        return response.message;
+    }
+
+    /** Encodes and sends a Bdx SendAccept message. */
+    async sendSendAccept(message: BdxSendAccept) {
+        await this.send({ kind: BdxMessageType.SendAccept, message });
+    }
+
+    /** Encodes and sends a Bdx ReceiveAccept message. */
+    async sendReceiveAccept(message: BdxReceiveAccept) {
+        await this.send({ kind: BdxMessageType.ReceiveAccept, message });
+    }
+
+    /** Encodes and sends a Bdx Block message. */
+    async sendBlock(message: BdxBlock) {
+        await this.send({ kind: BdxMessageType.Block, message });
+    }
+
+    /** Encodes and sends a Bdx BlockQuery message. */
+    async sendBlockQuery(message: BdxBlockQuery) {
+        await this.send({ kind: BdxMessageType.BlockQuery, message });
+    }
+
+    /** Encodes and sends a Bdx BlockQueryWithSkip message. */
+    async sendBlockQueryWithSkip(message: BdxBlockQueryWithSkip) {
+        await this.send({ kind: BdxMessageType.BlockQueryWithSkip, message });
+    }
+
+    /** Encodes and sends a Bdx BlockEof message. */
+    async sendBlockEof(message: BdxBlockEof) {
+        await this.send({ kind: BdxMessageType.BlockEof, message });
+    }
+
+    /** Encodes and sends a Bdx BlockAck message. */
+    async sendBlockAck(message: BdxBlockAck) {
+        await this.send({ kind: BdxMessageType.BlockAck, message });
+    }
+
+    /** Encodes and sends a Bdx BlockAckEof message */
+    async sendBlockAckEof(message: BdxBlockAckEof) {
+        await this.send({ kind: BdxMessageType.BlockAckEof, message });
+    }
+
+    /** Read the next Block message, accepts Block and BlockEof messages. Returns the decoded message and it's type. */
+    async readBlock(): Promise<BdxMessage<BdxMessageType.Block | BdxMessageType.BlockEof>> {
+        const block = await this.nextMessage([BdxMessageType.Block, BdxMessageType.BlockEof]);
+        if (BdxMessage.is(block, BdxMessageType.Block) && block.message.data.byteLength === 0) {
+            // a Block message must not have empty data
+            throw new BdxError("Received empty data in Block message", BdxStatusCode.BadMessageContent);
+        }
+        return block;
+    }
+
+    /**
+     * Read the next BlockQuery message, accepts BlockQuery and BlockQueryWithSkip and BlockAck messages.
+     * When a BlockAck is received, it will be validated and the next BlockQuery message will be read.
+     * Returns the decoded message and it's type.
+     */
+    async readBlockQuery(): Promise<BdxMessage<BdxMessageType.BlockQuery | BdxMessageType.BlockQueryWithSkip>> {
+        let response = await this.nextMessage([
+            BdxMessageType.BlockQuery,
+            BdxMessageType.BlockQueryWithSkip,
+            BdxMessageType.BlockAck,
+        ]);
+        let expectedBlockMessageCounter: number | undefined = undefined;
+        if (BdxMessage.is(response, BdxMessageType.BlockAck)) {
+            expectedBlockMessageCounter = (response.message.blockCounter + 1) % 0x100000000; // wrap around at 2^32
+            response = await this.nextMessage([BdxMessageType.BlockQuery, BdxMessageType.BlockQueryWithSkip]);
+        }
+
+        // Ensure that if we got an Ack Message that the blockCounter is as expected because this cannot be done outside
+        if (
+            expectedBlockMessageCounter !== undefined &&
+            response.message.blockCounter !== expectedBlockMessageCounter
+        ) {
+            throw new BdxError(
+                `Received BlockQuery with unexpected block counter: ${response.message.blockCounter}, expected: ${expectedBlockMessageCounter}`,
+                BdxStatusCode.BadBlockCounter,
+            );
+        }
+
+        return response;
+    }
+
+    /** Reads the next BlockAckEof message and returns the decoded message. */
+    async readBlockAckEof(): Promise<BdxBlockAckEof> {
+        const response = await this.nextMessage([BdxMessageType.BlockAckEof]);
+        BdxMessage.assert(response, BdxMessageType.BlockAckEof);
+        return response.message;
+    }
+
+    /** Reads the next BlockAck message and returns the decoded message. */
+    async readBlockAck(): Promise<BdxBlockAck> {
+        const response = await this.nextMessage([BdxMessageType.BlockAck]);
+        BdxMessage.assert(response, BdxMessageType.BlockAck);
+        return response.message;
+    }
+
+    /** Sends a Bdx Error StatusReport message with the given protocol status. */
+    sendError(code: BdxStatusCode) {
+        return this.#sendStatusReport(GeneralStatusCode.Failure, code);
+    }
+
+    /** Encodes and sends a Bdx StatusReport message with the given general and protocol status. */
+    async #sendStatusReport(generalStatus: GeneralStatusCode, protocolStatus: BdxStatusCode, requiresAck?: boolean) {
+        await this.#exchange.send(
+            SecureMessageType.StatusReport,
+            BdxStatusMessage.encode({
+                generalStatus,
+                protocolStatus,
+            }),
+            {
+                requiresAck,
+                logContext: {
+                    generalStatus: GeneralStatusCode[generalStatus] ?? Diagnostic.hex(generalStatus),
+                    protocolStatus: BdxStatusCode[protocolStatus] ?? Diagnostic.hex(protocolStatus),
+                },
+            },
+        );
+    }
+
+    protected throwIfErrorStatusReport(message: Message, logHint?: string) {
+        const {
+            payloadHeader: { messageType },
+            payload,
+        } = message;
+        if (messageType !== SecureMessageType.StatusReport) return;
+
+        const { generalStatus, protocolId, protocolStatus } = BdxStatusMessage.decode(payload);
+        if (generalStatus !== GeneralStatusCode.Success) {
+            throw new BdxStatusResponseError(
+                `Received general error status for protocol ${protocolId}${logHint ? ` (${logHint})` : ""}`,
+                generalStatus,
+                protocolStatus,
+            );
+        }
+        if (protocolStatus !== BdxStatusCode.Success) {
+            throw new BdxStatusResponseError(
+                `Received general success status, but protocol status is not Success${logHint ? ` (${logHint})` : ""}`,
+                generalStatus,
+                protocolStatus,
+            );
+        }
+    }
+
+    close() {
+        return this.#exchange.close();
+    }
+
+    /**
+     * Ensure that the value is a safe JavaScript "number" type and that it is not too large. Matter spec allows also
+     * 64bit values, but they make little sense for now, so make sure we handle them as too large. MAX_SAFE_INTEGER is
+     * 2^53-1 and is enough for now.
+     */
+    static asSafeNumber(
+        value: number | bigint | undefined,
+        context = "",
+        bdxErrorCode = BdxStatusCode.Unknown,
+    ): number {
+        if (typeof value !== "number" && typeof value !== "bigint") {
+            throw new InternalError(`${context} ${value} is not a number`); // Should not happen
+        }
+        if (value > Number.MAX_SAFE_INTEGER) {
+            throw new BdxError(`${context} ${value} exceeds maximum safe integer value`, bdxErrorCode);
+        }
+        return Number(value);
+    }
+}

package/src/bdx/BdxProtocol.ts

@@ -0,0 +1,93 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Logger, MatterError, StorageContext } from "#general";
+import { MessageExchange } from "#protocol/MessageExchange.js";
+import { ProtocolHandler } from "#protocol/ProtocolHandler.js";
+import { BDX_PROTOCOL_ID, BdxMessageType, BdxStatusCode } from "#types";
+import { Message } from "../codec/MessageCodec.js";
+import { BdxMessenger } from "./BdxMessenger.js";
+import { BdxSession } from "./BdxSession.js";
+import { BdxSessionConfiguration } from "./BdxSessionConfiguration.js";
+import { BdxInitMessageSchema } from "./schema/BdxInitMessagesSchema.js";
+
+const logger = Logger.get("BdxProtocol");
+
+/** BDX protocol handler. */
+export class BdxProtocol implements ProtocolHandler {
+    readonly id = BDX_PROTOCOL_ID;
+    readonly requiresSecureSession = true;
+    readonly #activeBdxSessions = new Map<MessageExchange, BdxSession>();
+    #storage: StorageContext;
+    #bdxLimits?: BdxSessionConfiguration.Config;
+
+    /**
+     * 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: StorageContext, options?: BdxSessionConfiguration.Config) {
+        this.#storage = storage;
+        this.#bdxLimits = options;
+    }
+
+    async onNewExchange(exchange: MessageExchange, message: 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: BdxMessenger, bdxSession: 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();
+    }
+}

package/src/bdx/BdxSession.ts

@@ -0,0 +1,174 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { AsyncObservable, ClassExtends, Diagnostic, Logger, StorageContext } from "#general";
+import { BdxMessageType, BdxStatusCode } from "#types";
+import { bdxSessionInitiator } from "./bdx-session-initiator.js";
+import { BdxError } from "./BdxError.js";
+import { BdxMessenger } from "./BdxMessenger.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 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 class BdxSession {
+    #messenger: BdxMessenger;
+    #started = false;
+    #closed = AsyncObservable();
+    #isClosed = false;
+
+    #config: BdxSessionConfiguration;
+
+    #transferFlow?: Flow;
+
+    /** Initializes a BdxSession as a sender, means that we upload data to the peer. */
+    static asSender(messenger: BdxMessenger, options: BdxSessionConfiguration.SenderInitiatorOptions): BdxSession {
+        return new BdxSession(messenger, { isSender: true, ...options });
+    }
+
+    /** Initializes a BdxSession as a receiver, means that we download data from the peer. */
+    static asReceiver(messenger: BdxMessenger, options: BdxSessionConfiguration.InitiatorOptions): BdxSession {
+        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: StorageContext,
+        messenger: BdxMessenger,
+        options: BdxSessionConfiguration.ReceiverOptions,
+    ): BdxSession {
+        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,
+        });
+    }
+
+    private constructor(messenger: BdxMessenger, options: BdxSessionConfiguration.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: Flow.TransferOptions): Flow {
+        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: ClassExtends<Flow>;
+        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?: unknown) {
+        if (this.#isClosed) {
+            return;
+        }
+        this.#isClosed = true;
+        await this.#transferFlow?.close(error);
+        await this.#closed.emit();
+    }
+}
+
+export namespace BdxSession {}

package/src/bdx/BdxSessionConfiguration.ts

@@ -0,0 +1,134 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ImplementationError } from "#general";
+import { BdxMessageType } from "#types";
+import { Flow } from "./flow/Flow.js";
+import { PersistedFileDesignator } from "./PersistedFileDesignator.js";
+import { BdxInit } from "./schema/BdxInitMessagesSchema.js";
+
+export class BdxSessionConfiguration {
+    #isSender: boolean;
+    #initMessage?: BdxInit;
+    #transferConfig: BdxSessionConfiguration.Config;
+    #fileDesignator: PersistedFileDesignator;
+
+    constructor(options: BdxSessionConfiguration.Options) {
+        const { isSender, fileDesignator, initMessage } = options;
+        this.#fileDesignator = fileDesignator;
+        this.#isSender = isSender;
+        this.#initMessage = initMessage;
+        this.#transferConfig = { ...BdxSessionConfiguration.DefaultConfig, ...options };
+
+        // Validate Config
+        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 !== undefined && maxBlockSize <= 0) {
+            throw new ImplementationError("Max block size must be greater than 0");
+        }
+        if (maxTransferSize !== undefined && 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 !== undefined || senderMaxLength !== undefined)) {
+            throw new ImplementationError("Sender start offset and sender max length are only supported for senders");
+        }
+    }
+
+    get isSender(): boolean {
+        return this.#isSender;
+    }
+
+    get initMessage(): BdxInit | undefined {
+        return this.#initMessage;
+    }
+
+    get isInitiator(): boolean {
+        return this.#initMessage === undefined;
+    }
+
+    get fileDesignator(): PersistedFileDesignator {
+        return this.#fileDesignator;
+    }
+
+    get transferConfig(): BdxSessionConfiguration.Config {
+        return this.#transferConfig;
+    }
+}
+
+export namespace BdxSessionConfiguration {
+    export 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; // not supported right now, so must be 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;
+    }
+
+    export const DefaultConfig: BdxSessionConfiguration.Config = {
+        preferredDriverModes: [
+            Flow.DriverMode.SenderDrive, // Default if multiple is supported, so lets use this
+            Flow.DriverMode.ReceiverDrive,
+        ],
+        asynchronousTransferAllowed: false, // Provisional, not supported
+        maxTransferSize: 1_024 * 100_000, // 100 MB, lets use that as maximum transfer filesize for now just to protect
+    };
+
+    export interface InitiatorOptions extends BdxSessionConfiguration.Config {
+        /** FileDesignator to use for the session. The value is usually pre-determined with the peer. */
+        fileDesignator: PersistedFileDesignator;
+    }
+
+    export 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;
+    }
+
+    export interface ReceiverOptions extends BdxSessionConfiguration.Config {
+        initMessageType: BdxMessageType;
+        initMessage: BdxInit; // The initial message received to start the session
+    }
+
+    export 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;
+    }
+}