androdex 1.1.3

package/src/secure-transport.js

@@ -0,0 +1,737 @@
+// FILE: secure-transport.js
+// Purpose: Owns the bridge-side E2EE handshake, envelope crypto, and reconnect catch-up buffer.
+// Layer: CLI helper
+// Exports: createBridgeSecureTransport, SECURE_PROTOCOL_VERSION, PAIRING_QR_VERSION
+// Depends on: crypto, ./secure-device-state
+
+const {
+  createCipheriv,
+  createDecipheriv,
+  createHash,
+  createPrivateKey,
+  createPublicKey,
+  diffieHellman,
+  generateKeyPairSync,
+  hkdfSync,
+  randomBytes,
+  randomUUID,
+  sign,
+  verify,
+} = require("crypto");
+const {
+  getTrustedPhonePublicKey,
+  rememberTrustedPhone,
+} = require("./secure-device-state");
+
+const PAIRING_QR_VERSION = 3;
+const SECURE_PROTOCOL_VERSION = 1;
+const HANDSHAKE_TAG = "androdex-e2ee-v1";
+const HANDSHAKE_MODE_QR_BOOTSTRAP = "qr_bootstrap";
+const HANDSHAKE_MODE_TRUSTED_RECONNECT = "trusted_reconnect";
+const SECURE_SENDER_MAC = "mac";
+const SECURE_SENDER_IPHONE = "iphone";
+const MAX_PAIRING_AGE_MS = 5 * 60 * 1000;
+const MAX_BRIDGE_OUTBOUND_MESSAGES = 500;
+const MAX_BRIDGE_OUTBOUND_BYTES = 10 * 1024 * 1024;
+
+function createBridgeSecureTransport({ hostId, sessionId, relayUrl, deviceState } = {}) {
+  const stableHostId = normalizeNonEmptyString(hostId)
+    || normalizeNonEmptyString(sessionId)
+    || normalizeNonEmptyString(deviceState?.hostId)
+    || randomUUID();
+  let currentDeviceState = deviceState;
+  let pendingHandshake = null;
+  let activeSession = null;
+  let liveSendWireMessage = null;
+  let currentPairingExpiresAt = Date.now() + MAX_PAIRING_AGE_MS;
+  let currentBootstrapToken = "";
+  let nextKeyEpoch = 1;
+  let nextBridgeOutboundSeq = 1;
+  let outboundBufferBytes = 0;
+  const outboundBuffer = [];
+
+  function createPairingPayload() {
+    currentPairingExpiresAt = Date.now() + MAX_PAIRING_AGE_MS;
+    currentBootstrapToken = randomUUID();
+    return {
+      v: PAIRING_QR_VERSION,
+      relay: relayUrl,
+      hostId: stableHostId,
+      macDeviceId: currentDeviceState.macDeviceId,
+      macIdentityPublicKey: currentDeviceState.macIdentityPublicKey,
+      bootstrapToken: currentBootstrapToken,
+      expiresAt: currentPairingExpiresAt,
+    };
+  }
+
+  function handleIncomingWireMessage(rawMessage, { sendControlMessage, onApplicationMessage }) {
+    const parsed = safeParseJSON(rawMessage);
+    if (!parsed || typeof parsed !== "object") {
+      return false;
+    }
+
+    const kind = normalizeNonEmptyString(parsed.kind);
+    if (!kind) {
+      if (parsed.method || parsed.id != null) {
+        sendControlMessage(createSecureError({
+          code: "update_required",
+          message: "This bridge requires the latest compatible Androdex mobile app for secure pairing.",
+        }));
+        return true;
+      }
+      return false;
+    }
+
+    switch (kind) {
+    case "clientHello":
+      handleClientHello(parsed, sendControlMessage);
+      return true;
+    case "clientAuth":
+      handleClientAuth(parsed, sendControlMessage);
+      return true;
+    case "resumeState":
+      handleResumeState(parsed);
+      return true;
+    case "encryptedEnvelope":
+      return handleEncryptedEnvelope(parsed, sendControlMessage, onApplicationMessage);
+    default:
+      return false;
+    }
+  }
+
+  function queueOutboundApplicationMessage(payloadText, sendWireMessage) {
+    const normalizedPayload = normalizeNonEmptyString(payloadText);
+    if (!normalizedPayload) {
+      return;
+    }
+
+    const bufferEntry = {
+      bridgeOutboundSeq: nextBridgeOutboundSeq,
+      payloadText: normalizedPayload,
+      sizeBytes: Buffer.byteLength(normalizedPayload, "utf8"),
+    };
+    nextBridgeOutboundSeq += 1;
+    outboundBuffer.push(bufferEntry);
+    outboundBufferBytes += bufferEntry.sizeBytes;
+    trimOutboundBuffer();
+
+    if (activeSession?.isResumed) {
+      sendBufferedEntry(bufferEntry, sendWireMessage);
+    }
+  }
+
+  function isSecureChannelReady() {
+    return Boolean(activeSession?.isResumed);
+  }
+
+  // Rejects QR bootstraps from a second mobile client unless it is the already-trusted device.
+  function hasConflictingTrustedPhone(phoneDeviceId, phoneIdentityPublicKey) {
+    const trustedPhones = currentDeviceState.trustedPhones || {};
+    return Object.entries(trustedPhones).some(([trustedDeviceId, trustedPublicKey]) => (
+      trustedDeviceId !== phoneDeviceId || trustedPublicKey !== phoneIdentityPublicKey
+    ));
+  }
+
+  function handleClientHello(message, sendControlMessage) {
+    const protocolVersion = Number(message.protocolVersion);
+    const incomingSessionId = normalizeNonEmptyString(message.hostId || message.sessionId);
+    const handshakeMode = normalizeNonEmptyString(message.handshakeMode);
+    const phoneDeviceId = normalizeNonEmptyString(message.phoneDeviceId);
+    const phoneIdentityPublicKey = normalizeNonEmptyString(message.phoneIdentityPublicKey);
+    const phoneEphemeralPublicKey = normalizeNonEmptyString(message.phoneEphemeralPublicKey);
+    const clientNonceBase64 = normalizeNonEmptyString(message.clientNonce);
+    const bootstrapToken = normalizeNonEmptyString(message.bootstrapToken);
+
+    if (protocolVersion !== SECURE_PROTOCOL_VERSION || incomingSessionId !== stableHostId) {
+      sendControlMessage(createSecureError({
+        code: "update_required",
+        message: "The bridge and mobile client are not using the same secure transport version.",
+      }));
+      return;
+    }
+
+    if (!phoneDeviceId || !phoneIdentityPublicKey || !phoneEphemeralPublicKey || !clientNonceBase64) {
+      sendControlMessage(createSecureError({
+        code: "invalid_client_hello",
+        message: "The mobile-client handshake is missing required secure fields.",
+      }));
+      return;
+    }
+
+    if (handshakeMode !== HANDSHAKE_MODE_QR_BOOTSTRAP && handshakeMode !== HANDSHAKE_MODE_TRUSTED_RECONNECT) {
+      sendControlMessage(createSecureError({
+        code: "invalid_handshake_mode",
+        message: "The mobile client requested an unknown secure pairing mode.",
+      }));
+      return;
+    }
+
+    if (handshakeMode === HANDSHAKE_MODE_QR_BOOTSTRAP && Date.now() > currentPairingExpiresAt) {
+      sendControlMessage(createSecureError({
+        code: "pairing_expired",
+        message: "The pairing QR code has expired. Generate a new QR code from the bridge.",
+      }));
+      return;
+    }
+    if (handshakeMode === HANDSHAKE_MODE_QR_BOOTSTRAP && bootstrapToken !== currentBootstrapToken) {
+      sendControlMessage(createSecureError({
+        code: "pairing_expired",
+        message: "The pairing token is no longer valid. Generate a new QR code from the daemon.",
+      }));
+      return;
+    }
+
+    const trustedPhonePublicKey = getTrustedPhonePublicKey(currentDeviceState, phoneDeviceId);
+    if (handshakeMode === HANDSHAKE_MODE_QR_BOOTSTRAP && hasConflictingTrustedPhone(phoneDeviceId, phoneIdentityPublicKey)) {
+      sendControlMessage(createSecureError({
+        code: "phone_replacement_required",
+        message: "This host is already paired with another mobile client. Reset pairing on the host before pairing a new device.",
+      }));
+      return;
+    }
+
+    if (handshakeMode === HANDSHAKE_MODE_TRUSTED_RECONNECT) {
+      if (!trustedPhonePublicKey) {
+        sendControlMessage(createSecureError({
+          code: "phone_not_trusted",
+          message: "This mobile client is not trusted by the current bridge session. Scan a fresh QR code to pair again.",
+        }));
+        return;
+      }
+      if (trustedPhonePublicKey !== phoneIdentityPublicKey) {
+        sendControlMessage(createSecureError({
+          code: "phone_identity_changed",
+          message: "The trusted mobile-client identity does not match this reconnect attempt.",
+        }));
+        return;
+      }
+    }
+
+    const clientNonce = base64ToBuffer(clientNonceBase64);
+    if (!clientNonce || clientNonce.length === 0) {
+      sendControlMessage(createSecureError({
+        code: "invalid_client_nonce",
+        message: "The mobile-client secure nonce could not be decoded.",
+      }));
+      return;
+    }
+
+    const ephemeral = generateKeyPairSync("x25519");
+    const privateJwk = ephemeral.privateKey.export({ format: "jwk" });
+    const publicJwk = ephemeral.publicKey.export({ format: "jwk" });
+    const serverNonce = randomBytes(32);
+    const keyEpoch = nextKeyEpoch;
+    const expiresAtForTranscript = handshakeMode === HANDSHAKE_MODE_QR_BOOTSTRAP
+      ? currentPairingExpiresAt
+      : 0;
+    const transcriptBytes = buildTranscriptBytes({
+      sessionId: stableHostId,
+      protocolVersion,
+      handshakeMode,
+      keyEpoch,
+      macDeviceId: currentDeviceState.macDeviceId,
+      phoneDeviceId,
+      macIdentityPublicKey: currentDeviceState.macIdentityPublicKey,
+      phoneIdentityPublicKey,
+      macEphemeralPublicKey: base64UrlToBase64(publicJwk.x),
+      phoneEphemeralPublicKey,
+      clientNonce,
+      serverNonce,
+      expiresAtForTranscript,
+    });
+    const macSignature = signTranscript(
+      currentDeviceState.macIdentityPrivateKey,
+      currentDeviceState.macIdentityPublicKey,
+      transcriptBytes
+    );
+    debugSecureLog(
+      `serverHello mode=${handshakeMode} session=${shortId(stableHostId)} keyEpoch=${keyEpoch} `
+      + `mac=${shortId(currentDeviceState.macDeviceId)} phone=${shortId(phoneDeviceId)} `
+      + `macKey=${shortFingerprint(currentDeviceState.macIdentityPublicKey)} `
+      + `phoneKey=${shortFingerprint(phoneIdentityPublicKey)} `
+      + `transcript=${transcriptDigest(transcriptBytes)}`
+    );
+
+    pendingHandshake = {
+      sessionId: stableHostId,
+      handshakeMode,
+      keyEpoch,
+      phoneDeviceId,
+      phoneIdentityPublicKey,
+      phoneEphemeralPublicKey,
+      macEphemeralPrivateKey: base64UrlToBase64(privateJwk.d),
+      macEphemeralPublicKey: base64UrlToBase64(publicJwk.x),
+      transcriptBytes,
+      expiresAtForTranscript,
+    };
+    activeSession = null;
+
+    sendControlMessage({
+      kind: "serverHello",
+      protocolVersion: SECURE_PROTOCOL_VERSION,
+      sessionId: stableHostId,
+      hostId: stableHostId,
+      handshakeMode,
+      macDeviceId: currentDeviceState.macDeviceId,
+      macIdentityPublicKey: currentDeviceState.macIdentityPublicKey,
+      macEphemeralPublicKey: pendingHandshake.macEphemeralPublicKey,
+      serverNonce: serverNonce.toString("base64"),
+      keyEpoch,
+      expiresAtForTranscript,
+      macSignature,
+      clientNonce: clientNonceBase64,
+    });
+  }
+
+  function handleClientAuth(message, sendControlMessage) {
+    if (!pendingHandshake) {
+      sendControlMessage(createSecureError({
+        code: "unexpected_client_auth",
+        message: "The bridge did not have a pending secure handshake to finalize.",
+      }));
+      return;
+    }
+
+    const incomingSessionId = normalizeNonEmptyString(message.hostId || message.sessionId);
+    const phoneDeviceId = normalizeNonEmptyString(message.phoneDeviceId);
+    const keyEpoch = Number(message.keyEpoch);
+    const phoneSignature = normalizeNonEmptyString(message.phoneSignature);
+    if (
+      incomingSessionId !== pendingHandshake.sessionId
+      || phoneDeviceId !== pendingHandshake.phoneDeviceId
+      || keyEpoch !== pendingHandshake.keyEpoch
+      || !phoneSignature
+    ) {
+      pendingHandshake = null;
+      sendControlMessage(createSecureError({
+        code: "invalid_client_auth",
+        message: "The secure client authentication payload was invalid.",
+      }));
+      return;
+    }
+
+    const clientAuthTranscript = Buffer.concat([
+      pendingHandshake.transcriptBytes,
+      encodeLengthPrefixedUTF8("client-auth"),
+    ]);
+    const phoneVerified = verifyTranscript(
+      pendingHandshake.phoneIdentityPublicKey,
+      clientAuthTranscript,
+      phoneSignature
+    );
+    if (!phoneVerified) {
+      pendingHandshake = null;
+      sendControlMessage(createSecureError({
+        code: "invalid_phone_signature",
+        message: "The mobile-client secure signature could not be verified.",
+      }));
+      return;
+    }
+
+    const sharedSecret = diffieHellman({
+      privateKey: createPrivateKey({
+        key: {
+          crv: "X25519",
+          d: base64ToBase64Url(pendingHandshake.macEphemeralPrivateKey),
+          kty: "OKP",
+          x: base64ToBase64Url(pendingHandshake.macEphemeralPublicKey),
+        },
+        format: "jwk",
+      }),
+      publicKey: createPublicKey({
+        key: {
+          crv: "X25519",
+          kty: "OKP",
+          x: base64ToBase64Url(pendingHandshake.phoneEphemeralPublicKey),
+        },
+        format: "jwk",
+      }),
+    });
+    const salt = createHash("sha256").update(pendingHandshake.transcriptBytes).digest();
+    const infoPrefix = [
+      HANDSHAKE_TAG,
+      pendingHandshake.sessionId,
+      currentDeviceState.macDeviceId,
+      pendingHandshake.phoneDeviceId,
+      String(pendingHandshake.keyEpoch),
+    ].join("|");
+
+    activeSession = {
+      sessionId: pendingHandshake.sessionId,
+      keyEpoch: pendingHandshake.keyEpoch,
+      phoneDeviceId: pendingHandshake.phoneDeviceId,
+      phoneIdentityPublicKey: pendingHandshake.phoneIdentityPublicKey,
+      phoneToMacKey: deriveAesKey(sharedSecret, salt, `${infoPrefix}|phoneToMac`),
+      macToPhoneKey: deriveAesKey(sharedSecret, salt, `${infoPrefix}|macToPhone`),
+      lastInboundCounter: -1,
+      nextOutboundCounter: 0,
+      isResumed: false,
+      sendWireMessage: liveSendWireMessage,
+    };
+
+    nextKeyEpoch = pendingHandshake.keyEpoch + 1;
+    if (
+      pendingHandshake.handshakeMode === HANDSHAKE_MODE_QR_BOOTSTRAP
+      || getTrustedPhonePublicKey(currentDeviceState, pendingHandshake.phoneDeviceId)
+    ) {
+      currentDeviceState = rememberTrustedPhone(
+        currentDeviceState,
+        pendingHandshake.phoneDeviceId,
+        pendingHandshake.phoneIdentityPublicKey
+      );
+    }
+    if (pendingHandshake.handshakeMode === HANDSHAKE_MODE_QR_BOOTSTRAP) {
+      resetOutboundReplayState();
+    }
+
+    pendingHandshake = null;
+    sendControlMessage({
+      kind: "secureReady",
+      sessionId: stableHostId,
+      hostId: stableHostId,
+      keyEpoch: activeSession.keyEpoch,
+      macDeviceId: currentDeviceState.macDeviceId,
+    });
+    currentBootstrapToken = "";
+  }
+
+  function handleResumeState(message) {
+    if (!activeSession) {
+      return;
+    }
+
+    const incomingSessionId = normalizeNonEmptyString(message.hostId || message.sessionId);
+    const keyEpoch = Number(message.keyEpoch);
+    if (incomingSessionId !== stableHostId || keyEpoch !== activeSession.keyEpoch) {
+      return;
+    }
+
+    const lastAppliedBridgeOutboundSeq = Number(message.lastAppliedBridgeOutboundSeq) || 0;
+    const missingEntries = outboundBuffer.filter(
+      (entry) => entry.bridgeOutboundSeq > lastAppliedBridgeOutboundSeq
+    );
+    activeSession.isResumed = true;
+    for (const entry of missingEntries) {
+      sendBufferedEntry(entry, messageText => {
+        if (typeof activeSession.sendWireMessage === "function") {
+          activeSession.sendWireMessage(messageText);
+        }
+      });
+    }
+  }
+
+  function handleEncryptedEnvelope(message, sendControlMessage, onApplicationMessage) {
+    if (!activeSession) {
+      sendControlMessage(createSecureError({
+        code: "secure_channel_unavailable",
+        message: "The secure channel is not ready yet on the bridge.",
+      }));
+      return true;
+    }
+
+    const incomingSessionId = normalizeNonEmptyString(message.hostId || message.sessionId);
+    const keyEpoch = Number(message.keyEpoch);
+    const sender = normalizeNonEmptyString(message.sender);
+    const counter = Number(message.counter);
+    if (
+      incomingSessionId !== stableHostId
+      || keyEpoch !== activeSession.keyEpoch
+      || sender !== SECURE_SENDER_IPHONE
+      || !Number.isInteger(counter)
+      || counter <= activeSession.lastInboundCounter
+    ) {
+      sendControlMessage(createSecureError({
+        code: "invalid_envelope",
+        message: "The bridge rejected an invalid or replayed secure envelope.",
+      }));
+      return true;
+    }
+
+    const plaintextBuffer = decryptEnvelopeBuffer(message, activeSession.phoneToMacKey, SECURE_SENDER_IPHONE, counter);
+    if (!plaintextBuffer) {
+      sendControlMessage(createSecureError({
+        code: "decrypt_failed",
+        message: "The bridge could not decrypt the secure payload from the mobile client.",
+      }));
+      return true;
+    }
+
+    activeSession.lastInboundCounter = counter;
+    const payloadObject = safeParseJSON(plaintextBuffer.toString("utf8"));
+    const payloadText = normalizeNonEmptyString(payloadObject?.payloadText);
+    if (!payloadText) {
+      sendControlMessage(createSecureError({
+        code: "invalid_payload",
+        message: "The secure payload did not contain a usable application message.",
+      }));
+      return true;
+    }
+
+    onApplicationMessage(payloadText);
+    return true;
+  }
+
+  function bindLiveSendWireMessage(sendWireMessage) {
+    liveSendWireMessage = sendWireMessage;
+    if (activeSession) {
+      activeSession.sendWireMessage = sendWireMessage;
+    }
+  }
+
+  function trimOutboundBuffer() {
+    while (
+      outboundBuffer.length > MAX_BRIDGE_OUTBOUND_MESSAGES
+      || outboundBufferBytes > MAX_BRIDGE_OUTBOUND_BYTES
+    ) {
+      const removed = outboundBuffer.shift();
+      if (!removed) {
+        break;
+      }
+      outboundBufferBytes = Math.max(0, outboundBufferBytes - removed.sizeBytes);
+    }
+  }
+
+  // Starts each fresh QR bootstrap with a clean catch-up window for the single trusted phone.
+  function resetOutboundReplayState() {
+    outboundBuffer.length = 0;
+    outboundBufferBytes = 0;
+    nextBridgeOutboundSeq = 1;
+  }
+
+  function sendBufferedEntry(entry, sendWireMessage) {
+    if (!activeSession?.isResumed) {
+      return;
+    }
+
+    const envelope = encryptEnvelopePayload(
+      {
+        bridgeOutboundSeq: entry.bridgeOutboundSeq,
+        payloadText: entry.payloadText,
+      },
+      activeSession.macToPhoneKey,
+      SECURE_SENDER_MAC,
+      activeSession.nextOutboundCounter,
+      stableHostId,
+      activeSession.keyEpoch
+    );
+    activeSession.nextOutboundCounter += 1;
+    sendWireMessage(JSON.stringify(envelope));
+  }
+
+  return {
+    PAIRING_QR_VERSION,
+    SECURE_PROTOCOL_VERSION,
+    bindLiveSendWireMessage,
+    createPairingPayload,
+    getCurrentDeviceState() {
+      return currentDeviceState;
+    },
+    handleIncomingWireMessage,
+    isSecureChannelReady,
+    queueOutboundApplicationMessage,
+  };
+}
+
+function debugSecureLog(message) {
+  console.log(`[androdex][secure] ${message}`);
+}
+
+function shortId(value) {
+  const normalized = normalizeNonEmptyString(value);
+  return normalized ? normalized.slice(0, 8) : "none";
+}
+
+function shortFingerprint(publicKeyBase64) {
+  const bytes = base64ToBuffer(publicKeyBase64);
+  if (!bytes || bytes.length === 0) {
+    return "invalid";
+  }
+  return createHash("sha256").update(bytes).digest("hex").slice(0, 12);
+}
+
+function transcriptDigest(transcriptBytes) {
+  return createHash("sha256").update(transcriptBytes).digest("hex").slice(0, 16);
+}
+
+function encryptEnvelopePayload(payloadObject, key, sender, counter, sessionId, keyEpoch) {
+  const nonce = nonceForDirection(sender, counter);
+  const cipher = createCipheriv("aes-256-gcm", key, nonce);
+  const ciphertext = Buffer.concat([
+    cipher.update(Buffer.from(JSON.stringify(payloadObject), "utf8")),
+    cipher.final(),
+  ]);
+  const tag = cipher.getAuthTag();
+
+  return {
+    kind: "encryptedEnvelope",
+    v: SECURE_PROTOCOL_VERSION,
+    sessionId,
+    keyEpoch,
+    sender,
+    counter,
+    ciphertext: ciphertext.toString("base64"),
+    tag: tag.toString("base64"),
+  };
+}
+
+function decryptEnvelopeBuffer(envelope, key, sender, counter) {
+  try {
+    const nonce = nonceForDirection(sender, counter);
+    const decipher = createDecipheriv("aes-256-gcm", key, nonce);
+    decipher.setAuthTag(base64ToBuffer(envelope.tag));
+    return Buffer.concat([
+      decipher.update(base64ToBuffer(envelope.ciphertext)),
+      decipher.final(),
+    ]);
+  } catch {
+    return null;
+  }
+}
+
+function deriveAesKey(sharedSecret, salt, infoLabel) {
+  return Buffer.from(hkdfSync("sha256", sharedSecret, salt, Buffer.from(infoLabel, "utf8"), 32));
+}
+
+function signTranscript(privateKeyBase64, publicKeyBase64, transcriptBytes) {
+  const signature = sign(
+    null,
+    transcriptBytes,
+    createPrivateKey({
+      key: {
+        crv: "Ed25519",
+        d: base64ToBase64Url(privateKeyBase64),
+        kty: "OKP",
+        x: base64ToBase64Url(publicKeyBase64),
+      },
+      format: "jwk",
+    })
+  );
+  return signature.toString("base64");
+}
+
+function verifyTranscript(publicKeyBase64, transcriptBytes, signatureBase64) {
+  try {
+    return verify(
+      null,
+      transcriptBytes,
+      createPublicKey({
+        key: {
+          crv: "Ed25519",
+          kty: "OKP",
+          x: base64ToBase64Url(publicKeyBase64),
+        },
+        format: "jwk",
+      }),
+      base64ToBuffer(signatureBase64)
+    );
+  } catch {
+    return false;
+  }
+}
+
+function buildTranscriptBytes({
+  sessionId,
+  protocolVersion,
+  handshakeMode,
+  keyEpoch,
+  macDeviceId,
+  phoneDeviceId,
+  macIdentityPublicKey,
+  phoneIdentityPublicKey,
+  macEphemeralPublicKey,
+  phoneEphemeralPublicKey,
+  clientNonce,
+  serverNonce,
+  expiresAtForTranscript,
+}) {
+  return Buffer.concat([
+    encodeLengthPrefixedUTF8(HANDSHAKE_TAG),
+    encodeLengthPrefixedUTF8(sessionId),
+    encodeLengthPrefixedUTF8(String(protocolVersion)),
+    encodeLengthPrefixedUTF8(handshakeMode),
+    encodeLengthPrefixedUTF8(String(keyEpoch)),
+    encodeLengthPrefixedUTF8(macDeviceId),
+    encodeLengthPrefixedUTF8(phoneDeviceId),
+    encodeLengthPrefixedBuffer(base64ToBuffer(macIdentityPublicKey)),
+    encodeLengthPrefixedBuffer(base64ToBuffer(phoneIdentityPublicKey)),
+    encodeLengthPrefixedBuffer(base64ToBuffer(macEphemeralPublicKey)),
+    encodeLengthPrefixedBuffer(base64ToBuffer(phoneEphemeralPublicKey)),
+    encodeLengthPrefixedBuffer(clientNonce),
+    encodeLengthPrefixedBuffer(serverNonce),
+    encodeLengthPrefixedUTF8(String(expiresAtForTranscript)),
+  ]);
+}
+
+function encodeLengthPrefixedUTF8(value) {
+  return encodeLengthPrefixedBuffer(Buffer.from(String(value), "utf8"));
+}
+
+function encodeLengthPrefixedBuffer(buffer) {
+  const lengthBuffer = Buffer.allocUnsafe(4);
+  lengthBuffer.writeUInt32BE(buffer.length, 0);
+  return Buffer.concat([lengthBuffer, buffer]);
+}
+
+function nonceForDirection(sender, counter) {
+  const nonce = Buffer.alloc(12, 0);
+  nonce.writeUInt8(sender === SECURE_SENDER_MAC ? 1 : 2, 0);
+  let value = BigInt(counter);
+  for (let index = 11; index >= 1; index -= 1) {
+    nonce[index] = Number(value & 0xffn);
+    value >>= 8n;
+  }
+  return nonce;
+}
+
+function createSecureError({ code, message }) {
+  return {
+    kind: "secureError",
+    code,
+    message,
+  };
+}
+
+function normalizeNonEmptyString(value) {
+  if (typeof value !== "string") {
+    return "";
+  }
+  return value.trim();
+}
+
+function safeParseJSON(value) {
+  if (typeof value !== "string") {
+    return null;
+  }
+
+  try {
+    return JSON.parse(value);
+  } catch {
+    return null;
+  }
+}
+
+function base64ToBuffer(value) {
+  try {
+    return Buffer.from(value, "base64");
+  } catch {
+    return null;
+  }
+}
+
+function base64UrlToBase64(value) {
+  const padded = `${value}${"=".repeat((4 - (value.length % 4 || 4)) % 4)}`;
+  return padded.replace(/-/g, "+").replace(/_/g, "/");
+}
+
+function base64ToBase64Url(value) {
+  return value.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+
+module.exports = {
+  HANDSHAKE_MODE_QR_BOOTSTRAP,
+  HANDSHAKE_MODE_TRUSTED_RECONNECT,
+  PAIRING_QR_VERSION,
+  SECURE_PROTOCOL_VERSION,
+  createBridgeSecureTransport,
+  nonceForDirection,
+};