@push.rocks/smartrust 2.2.0 → 2.4.0

package/ts/classes.rustbridge.ts

@@ -35,6 +35,11 @@ interface IPendingRequest {
   abortHandler?: () => void;
   streaming?: StreamingResponse<any, any>;
   admissionReservation?: IRequestAdmissionReservation;
+  sensitive?: {
+    byteLength: number;
+    writeComplete: boolean;
+    response: IManagementResponse | null;
+  };
 }
 
 interface IRequestAdmissionReservation {
@@ -73,6 +78,9 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
   private lifecycleGeneration = 0;
   private activationPromise: Promise<boolean> | null = null;
   private terminationPromise: Promise<void> | null = null;
+  private sensitiveRequestId: string | null = null;
+  private sensitiveUsedGeneration: number | null = null;
+  private regularRequestPreparations = 0;
 
   constructor(options: IRustBridgeOptions) {
     super();
@@ -89,6 +97,11 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
         }
       }
     }
+    if (options.sensitiveByteChannel
+      && (!Number.isSafeInteger(options.sensitiveByteChannel.maxPayloadSize)
+        || options.sensitiveByteChannel.maxPayloadSize <= 0)) {
+      throw new RangeError('RustBridge sensitiveByteChannel maxPayloadSize must be a positive safe integer');
+    }
     if (options.maxPendingRequestsByMethod) {
       for (const [method, limit] of Object.entries(options.maxPendingRequestsByMethod)) {
         if (!method || !Number.isSafeInteger(limit) || limit <= 0) {
@@ -109,6 +122,9 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
       inheritedFileDescriptors: options.inheritedFileDescriptors
         ? [...options.inheritedFileDescriptors]
         : undefined,
+      sensitiveByteChannel: options.sensitiveByteChannel
+        ? { ...options.sensitiveByteChannel }
+        : undefined,
       maxPendingRequestsByMethod: options.maxPendingRequestsByMethod
         ? { ...options.maxPendingRequestsByMethod }
         : undefined,
@@ -137,6 +153,7 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
         cliArgs: this.options.cliArgs,
         env: this.options.env,
         inheritedFileDescriptors: this.options.inheritedFileDescriptors,
+        sensitiveByteChannel: this.options.sensitiveByteChannel,
         maxPayloadSize: this.options.maxPayloadSize,
         terminationGracePeriodMs: this.options.terminationGracePeriodMs,
         logger: this.logger,
@@ -152,9 +169,9 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
    * @param socketOptions - Optional socket connection options (reconnect, etc.)
    */
   public connect(socketPath: string, socketOptions?: ISocketConnectOptions): Promise<boolean> {
-    if (this.options.inheritedFileDescriptors?.length) {
+    if (this.options.inheritedFileDescriptors?.length || this.options.sensitiveByteChannel) {
       return Promise.reject(
-        new Error('RustBridge inheritedFileDescriptors are available only with spawn()'),
+        new Error('RustBridge inheritedFileDescriptors and sensitiveByteChannel are available only with spawn()'),
       );
     }
     return this.activate(async () => new SocketTransport({
@@ -192,6 +209,8 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
     }
 
     const generation = ++this.lifecycleGeneration;
+    this.sensitiveRequestId = null;
+    this.sensitiveUsedGeneration = null;
     this.lifecycleState = 'starting';
 
     const activationPromise = (async (): Promise<boolean> => {
@@ -454,16 +473,25 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
       );
     }
 
+    if (this.sensitiveRequestId !== null) {
+      throw new RustBridgeRequestError(
+        `Command '${method}' cannot overlap the sensitive byte request`,
+        { code: 'ERR_RUST_BRIDGE_REQUEST_SENSITIVE_STATE', method },
+      );
+    }
+
     const transport = this.transport;
     if (!transport?.connected || !this.isRunning) {
       throw new Error(`${this.options.binaryName} bridge is not running`);
     }
 
     const lifecycleGeneration = this.lifecycleGeneration;
-    const admissionReservation = this.reservePendingRequest(method);
+    this.regularRequestPreparations++;
+    let admissionReservation: IRequestAdmissionReservation | undefined;
     let reservationTransferred = false;
 
     try {
+      admissionReservation = this.reservePendingRequest(method);
       const id = `req_${++this.requestCounter}`;
       const request: IManagementRequest = { id, method, params };
       const json = JSON.stringify(request);
@@ -581,12 +609,198 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
         }
       });
     } finally {
+      this.regularRequestPreparations--;
       if (!reservationTransferred) {
         this.releasePendingRequestReservation(admissionReservation);
       }
     }
   }
 
+  /**
+   * Send one request whose raw sensitive bytes travel on the generation-owned
+   * binary pipe. JSON carries only correlation, descriptor and length metadata.
+   *
+   * The supplied mutable view is exclusively owned by this call until it
+   * settles. Smartrust clears that exact view after the local write callback or
+   * failure; it cannot promise erasure of aliases, runtime or kernel copies, or
+   * receiver-owned memory.
+   */
+  public async sendCommandWithSensitiveBytes<K extends string & keyof TCommands>(
+    method: K,
+    params: TCommands[K]['params'],
+    bytes: Uint8Array<ArrayBuffer>,
+    options?: IRustBridgeRequestOptions,
+  ): Promise<TCommands[K]['result']> {
+    let cleared = false;
+    let admitted = false;
+    let reservationTransferred = false;
+    let admissionReservation: IRequestAdmissionReservation | undefined;
+    let ownedRequestId: string | null = null;
+    let ownedBytes: Uint8Array<ArrayBuffer> | null = null;
+    const clear = (): void => {
+      if (!cleared && ownedBytes) {
+        Uint8Array.prototype.fill.call(ownedBytes, 0);
+        cleared = true;
+      }
+    };
+
+    try {
+      const timeoutMs = options?.timeoutMs ?? this.options.requestTimeoutMs;
+      if (options?.timeoutMs !== undefined
+        && (!Number.isSafeInteger(options.timeoutMs) || options.timeoutMs <= 0)) {
+        throw new RangeError('RustBridge request timeoutMs must be a positive safe integer');
+      }
+      if (!(bytes instanceof Uint8Array) || !(bytes.buffer instanceof ArrayBuffer)) {
+        throw new TypeError('RustBridge sensitive bytes must use an ArrayBuffer-backed Uint8Array');
+      }
+      ownedBytes = new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+      const maxPayloadSize = this.options.sensitiveByteChannel?.maxPayloadSize;
+      if (maxPayloadSize === undefined) {
+        throw new RustBridgeRequestError(
+          `Command '${method}' requires sensitiveByteChannel`,
+          { code: 'ERR_RUST_BRIDGE_REQUEST_SENSITIVE_STATE', method },
+        );
+      }
+      if (ownedBytes.byteLength > maxPayloadSize) {
+        throw new RangeError(
+          `Sensitive byte payload exceeds maxPayloadSize (${ownedBytes.byteLength} > ${maxPayloadSize})`,
+        );
+      }
+      if (options?.signal?.aborted) {
+        throw new RustBridgeRequestError(
+          `Command '${method}' was aborted before it was sent`,
+          { code: 'ERR_RUST_BRIDGE_REQUEST_ABORTED', method, cause: options.signal.reason },
+        );
+      }
+
+      const transport = this.transport;
+      const lifecycleGeneration = this.lifecycleGeneration;
+      if (!transport?.connected || !this.isRunning) {
+        throw new Error(`${this.options.binaryName} bridge is not running`);
+      }
+      if (!transport.writeSensitiveFrame || !Number.isSafeInteger(transport.sensitiveFileDescriptor)
+        || (transport.sensitiveFileDescriptor as number) < 3) {
+        throw new RustBridgeRequestError(
+          `Command '${method}' has no owned sensitive byte pipe`,
+          { code: 'ERR_RUST_BRIDGE_REQUEST_SENSITIVE_STATE', method },
+        );
+      }
+      if (this.sensitiveRequestId !== null || this.sensitiveUsedGeneration === lifecycleGeneration
+        || this.pendingRequests.size !== 0 || this.regularRequestPreparations !== 0) {
+        throw new RustBridgeRequestError(
+          `Command '${method}' cannot acquire the one-shot sensitive byte pipe`,
+          { code: 'ERR_RUST_BRIDGE_REQUEST_SENSITIVE_STATE', method },
+        );
+      }
+
+      admissionReservation = this.reservePendingRequest(method);
+      const id = `req_${++this.requestCounter}`;
+      ownedRequestId = id;
+      this.sensitiveRequestId = id;
+      this.sensitiveUsedGeneration = lifecycleGeneration;
+      admitted = true;
+      const request: IManagementRequest = {
+        id,
+        method,
+        params,
+        sensitive: {
+          protocol: 'smartrust-sensitive-v1',
+          fileDescriptor: transport.sensitiveFileDescriptor as number,
+          byteLength: ownedBytes.byteLength,
+        },
+      };
+      const json = JSON.stringify(request);
+      const byteLength = Buffer.byteLength(json, 'utf8');
+      if (byteLength > this.options.maxPayloadSize) {
+        throw new Error(
+          `Outbound message exceeds maxPayloadSize (${byteLength} > ${this.options.maxPayloadSize})`,
+        );
+      }
+      const availabilityError = this.getRequestAvailabilityError(
+        method, options?.signal, transport, lifecycleGeneration,
+      );
+      if (availabilityError) throw availabilityError;
+
+      const result = await new Promise<TCommands[K]['result']>((resolve, reject) => {
+        const pending: IPendingRequest = {
+          resolve,
+          reject,
+          timer: null,
+          method,
+          abortSignal: options?.signal,
+          admissionReservation,
+          sensitive: { byteLength: ownedBytes!.byteLength, writeComplete: false, response: null },
+        };
+        this.pendingRequests.set(id, pending);
+        reservationTransferred = true;
+
+        if (options?.signal) {
+          pending.abortHandler = () => {
+            this.settlePendingRequest(id, {
+              outcome: 'reject',
+              error: new RustBridgeRequestError(`Command '${method}' was aborted`, {
+                code: 'ERR_RUST_BRIDGE_REQUEST_ABORTED', requestId: id, method,
+                cause: options.signal?.reason,
+              }),
+            });
+          };
+          options.signal.addEventListener('abort', pending.abortHandler, { once: true });
+        }
+        pending.timer = setTimeout(() => {
+          this.settlePendingRequest(id, {
+            outcome: 'reject',
+            error: new RustBridgeRequestError(`Command '${method}' timed out after ${timeoutMs}ms`, {
+              code: 'ERR_RUST_BRIDGE_REQUEST_TIMEOUT', requestId: id, method,
+            }),
+          });
+        }, timeoutMs);
+
+        void (async (): Promise<void> => {
+          try {
+            const currentAvailabilityError = this.getRequestAvailabilityError(
+              method, options?.signal, transport, lifecycleGeneration, id,
+            );
+            if (currentAvailabilityError) throw currentAvailabilityError;
+            await transport.write(json + '\n');
+            await transport.writeSensitiveFrame!(id, ownedBytes!);
+            clear();
+            this.markSensitiveWriteComplete(id);
+          } catch (error: unknown) {
+            try { clear(); } catch (clearError: unknown) {
+              error = new AggregateError([error, clearError], 'Sensitive byte write and clearing failed');
+            }
+            this.settlePendingRequest(id, {
+              outcome: 'reject',
+              error: error instanceof RustBridgeRequestError
+                ? error
+                : new RustBridgeRequestError(
+                  `Failed to write sensitive byte request: ${this.getErrorMessage(error)}`,
+                  { code: 'ERR_RUST_BRIDGE_REQUEST_WRITE', requestId: id, method, cause: error },
+                ),
+            });
+          }
+        })();
+      });
+      return result;
+    } catch (error: unknown) {
+      if (admitted) {
+        try {
+          await this.terminate();
+        } catch (terminationError: unknown) {
+          throw new AggregateError([error, terminationError], 'Sensitive request failed and child termination was not confirmed');
+        }
+      }
+      throw error;
+    } finally {
+      try { clear(); } finally {
+        if (!reservationTransferred) this.releasePendingRequestReservation(admissionReservation);
+        if (ownedRequestId !== null && this.sensitiveRequestId === ownedRequestId) {
+          this.sensitiveRequestId = null;
+        }
+      }
+    }
+  }
+
   /**
    * Send a streaming command to the Rust process.
    * Returns a StreamingResponse that yields chunks via `for await...of`
@@ -598,6 +812,14 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
   ): StreamingResponse<TExtractChunk<TCommands[K]>, TCommands[K]['result']> {
     const streaming = new StreamingResponse<TExtractChunk<TCommands[K]>, TCommands[K]['result']>();
 
+    if (this.sensitiveRequestId !== null) {
+      streaming.fail(new RustBridgeRequestError(
+        `Command '${method}' cannot overlap the sensitive byte request`,
+        { code: 'ERR_RUST_BRIDGE_REQUEST_SENSITIVE_STATE', method },
+      ));
+      return streaming;
+    }
+
     const transport = this.transport;
     if (!transport?.connected || !this.isRunning) {
       streaming.fail(new Error(`${this.options.binaryName} bridge is not running`));
@@ -608,6 +830,7 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
     let admissionReservation: IRequestAdmissionReservation | undefined;
     let reservationTransferred = false;
     let requestId: string | undefined;
+    this.regularRequestPreparations++;
 
     try {
       admissionReservation = this.reservePendingRequest(method);
@@ -709,6 +932,7 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
         streaming.fail(error);
       }
     } finally {
+      this.regularRequestPreparations--;
       if (!reservationTransferred) {
         this.releasePendingRequestReservation(admissionReservation);
       }
@@ -880,33 +1104,64 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
       const response = parsed as IManagementResponse;
       const pending = this.pendingRequests.get(response.id);
       if (pending) {
-        if (response.success) {
-          this.settlePendingRequest(response.id, {
-            outcome: 'resolve',
-            value: response.result,
-          });
-        } else {
-          const message = response.error || 'Unknown error from Rust process';
-          this.settlePendingRequest(response.id, {
-            outcome: 'reject',
-            error: new RustBridgeRequestError(
-              message,
-              {
-                code: 'ERR_RUST_BRIDGE_REQUEST_RUST_RESPONSE',
-                responseErrorCode:
-                  typeof response.errorCode === 'string'
-                    ? response.errorCode
-                    : undefined,
-                requestId: response.id,
-                method: pending.method,
-              },
-            ),
-          });
-        }
+        if (pending.sensitive) this.acceptSensitiveResponse(response, pending);
+        else this.settleManagementResponse(response, pending);
       }
     }
   }
 
+  private acceptSensitiveResponse(response: IManagementResponse, pending: IPendingRequest): void {
+    const state = pending.sensitive!;
+    const ack = response.sensitiveAck;
+    if (state.response !== null || typeof response.success !== 'boolean'
+      || !ack || typeof ack !== 'object' || Array.isArray(ack)
+      || Object.keys(ack).sort().join(',') !== 'byteLength,consumed,protocol'
+      || ack.protocol !== 'smartrust-sensitive-v1' || ack.consumed !== true
+      || ack.byteLength !== state.byteLength) {
+      this.settlePendingRequest(response.id, {
+        outcome: 'reject',
+        error: new RustBridgeRequestError(
+          `Command '${pending.method}' returned an invalid sensitive byte acknowledgement`,
+          {
+            code: 'ERR_RUST_BRIDGE_REQUEST_SENSITIVE_PROTOCOL',
+            requestId: response.id,
+            method: pending.method,
+          },
+        ),
+      });
+      return;
+    }
+    state.response = response;
+    if (state.writeComplete) this.settleManagementResponse(response, pending);
+  }
+
+  private markSensitiveWriteComplete(id: string): void {
+    const pending = this.pendingRequests.get(id);
+    if (!pending?.sensitive) return;
+    pending.sensitive.writeComplete = true;
+    if (pending.sensitive.response) {
+      this.settleManagementResponse(pending.sensitive.response, pending);
+    }
+  }
+
+  private settleManagementResponse(response: IManagementResponse, pending: IPendingRequest): void {
+    if (response.success) {
+      this.settlePendingRequest(response.id, { outcome: 'resolve', value: response.result });
+      return;
+    }
+    const message = response.error || 'Unknown error from Rust process';
+    this.settlePendingRequest(response.id, {
+      outcome: 'reject',
+      error: new RustBridgeRequestError(message, {
+        code: 'ERR_RUST_BRIDGE_REQUEST_RUST_RESPONSE',
+        responseErrorCode: typeof response.errorCode === 'string' ? response.errorCode : undefined,
+        responseErrorData: response.errorData,
+        requestId: response.id,
+        method: pending.method,
+      }),
+    });
+  }
+
   private settlePendingRequest(
     id: string,
     settlement: TPendingRequestSettlement,

package/ts/classes.rustbridgerequesterror.ts

@@ -7,11 +7,14 @@ export type TRustBridgeRequestErrorCode =
   | 'ERR_RUST_BRIDGE_REQUEST_LIMIT'
   | 'ERR_RUST_BRIDGE_REQUEST_WRITE'
   | 'ERR_RUST_BRIDGE_REQUEST_TRANSPORT'
+  | 'ERR_RUST_BRIDGE_REQUEST_SENSITIVE_STATE'
+  | 'ERR_RUST_BRIDGE_REQUEST_SENSITIVE_PROTOCOL'
   | 'ERR_RUST_BRIDGE_REQUEST_RUST_RESPONSE';
 
 export interface IRustBridgeRequestErrorOptions {
   code: TRustBridgeRequestErrorCode;
   responseErrorCode?: string;
+  responseErrorData?: unknown;
   requestId?: string;
   method?: string;
   cause?: unknown;
@@ -27,6 +30,8 @@ export interface IRustBridgeRequestErrorOptions {
 export class RustBridgeRequestError extends Error {
   public readonly code: TRustBridgeRequestErrorCode;
   public readonly responseErrorCode?: string;
+  /** Structured details from the Rust error response's `errorData`, as sent. */
+  public readonly responseErrorData?: unknown;
   public readonly requestId?: string;
   public readonly method?: string;
 
@@ -35,6 +40,7 @@ export class RustBridgeRequestError extends Error {
     this.name = 'RustBridgeRequestError';
     this.code = options.code;
     this.responseErrorCode = options.responseErrorCode;
+    this.responseErrorData = options.responseErrorData;
     this.requestId = options.requestId;
     this.method = options.method;
   }

package/ts/classes.stdiotransport.ts

@@ -8,12 +8,15 @@ import type {
 
 const DEFAULT_DISCONNECT_GRACE_PERIOD_MS = 5000;
 const MAX_TIMER_DELAY_MS = 2_147_483_647;
+const SENSITIVE_FRAME_HEADER_SIZE = 16;
+const SENSITIVE_FRAME_MAGIC = 'SMRS';
 
 export interface IStdioTransportOptions {
   binaryPath: string;
   cliArgs: string[];
   env?: Record<string, string>;
   inheritedFileDescriptors?: readonly number[];
+  sensitiveByteChannel?: { maxPayloadSize: number };
   maxPayloadSize: number;
   /** Default for every cleanup path, including automatic stdin failure. */
   terminationGracePeriodMs?: number;
@@ -34,6 +37,9 @@ interface IStdioTransportGeneration {
   sigtermAttempted: boolean;
   sigkillAttempted: boolean;
   sigtermError: Error | null;
+  sensitiveWriter: plugins.stream.Writable | null;
+  sensitiveUsed: boolean;
+  sensitiveError: Error | null;
 }
 
 /**
@@ -53,7 +59,17 @@ export class StdioTransport extends plugins.events.EventEmitter implements IRust
       && (!Number.isSafeInteger(options.terminationGracePeriodMs) || options.terminationGracePeriodMs < 0)) {
       throw new RangeError('StdioTransport terminationGracePeriodMs must be a non-negative safe integer');
     }
-    this.options = { ...options };
+    if (options.sensitiveByteChannel
+      && (!Number.isSafeInteger(options.sensitiveByteChannel.maxPayloadSize)
+        || options.sensitiveByteChannel.maxPayloadSize <= 0)) {
+      throw new RangeError('StdioTransport sensitiveByteChannel maxPayloadSize must be a positive safe integer');
+    }
+    this.options = {
+      ...options,
+      sensitiveByteChannel: options.sensitiveByteChannel
+        ? { ...options.sensitiveByteChannel }
+        : undefined,
+    };
     this.lineScanner = new LineScanner(options.maxPayloadSize, options.logger);
   }
 
@@ -61,6 +77,12 @@ export class StdioTransport extends plugins.events.EventEmitter implements IRust
     return this._connected;
   }
 
+  public get sensitiveFileDescriptor(): number | null {
+    return this.options.sensitiveByteChannel
+      ? 3 + (this.options.inheritedFileDescriptors?.length ?? 0)
+      : null;
+  }
+
   /**
    * Spawn the child process. Resolves when the process is running (not necessarily ready).
    */
@@ -82,6 +104,7 @@ export class StdioTransport extends plugins.events.EventEmitter implements IRust
         'pipe',
         'pipe',
         ...(this.options.inheritedFileDescriptors ?? []),
+        ...(this.options.sensitiveByteChannel ? ['pipe' as const] : []),
       ];
       childProcess = plugins.childProcess.spawn(
         this.options.binaryPath,
@@ -96,6 +119,12 @@ export class StdioTransport extends plugins.events.EventEmitter implements IRust
     const closePromise = new Promise<void>((resolve) => {
       resolveClose = resolve;
     });
+    const sensitiveEndpoint = this.options.sensitiveByteChannel
+      ? childProcess.stdio[this.sensitiveFileDescriptor!]
+      : null;
+    const sensitiveWriter = sensitiveEndpoint instanceof plugins.stream.Writable
+      ? sensitiveEndpoint
+      : null;
     const generation: IStdioTransportGeneration = {
       childProcess,
       stderrRemainder: '',
@@ -110,6 +139,9 @@ export class StdioTransport extends plugins.events.EventEmitter implements IRust
       sigtermAttempted: false,
       sigkillAttempted: false,
       sigtermError: null,
+      sensitiveWriter,
+      sensitiveUsed: false,
+      sensitiveError: null,
     };
 
     this.generation = generation;
@@ -151,6 +183,23 @@ export class StdioTransport extends plugins.events.EventEmitter implements IRust
       });
     });
 
+    generation.sensitiveWriter?.on('error', (error: Error) => {
+      if (generation.sensitiveError) return;
+      generation.sensitiveError = error;
+      if (this.generation !== generation || generation.closed) return;
+      this._connected = false;
+      queueMicrotask(() => {
+        if (this.generation !== generation || generation.closed) return;
+        void this.disconnectAndWait().catch((disconnectError: unknown) => {
+          this.options.logger.log('error', 'Failed to clean up child after sensitive pipe error: '
+            + this.getErrorMessage(disconnectError));
+        });
+        if (this.listenerCount('error') > 0) this.emit('error', error);
+        else if (generation.disconnectPromise) this.options.logger.log('error', 'Sensitive pipe error during disconnect: ' + error.message);
+        else this.emit('error', error);
+      });
+    });
+
     // Handle stderr with cross-chunk buffering.
     childProcess.stderr?.on('data', (data: Buffer) => {
       if (this.generation !== generation || generation.closed) {
@@ -198,6 +247,7 @@ export class StdioTransport extends plugins.events.EventEmitter implements IRust
         this.destroyOwnedStdioEndpoint(generation, 'stdin');
         this.destroyOwnedStdioEndpoint(generation, 'stdout');
         this.destroyOwnedStdioEndpoint(generation, 'stderr');
+        this.destroySensitiveEndpoint(generation);
       });
     });
 
@@ -285,6 +335,49 @@ export class StdioTransport extends plugins.events.EventEmitter implements IRust
     });
   }
 
+  /**
+   * Write the single sensitive frame owned by this child generation. The frame
+   * header and request id are non-secret; `data` is written without converting
+   * it to a string or copying its backing ArrayBuffer.
+   */
+  public async writeSensitiveFrame(
+    requestId: string,
+    data: Uint8Array<ArrayBuffer>,
+  ): Promise<void> {
+    if (!(data instanceof Uint8Array) || !(data.buffer instanceof ArrayBuffer)) {
+      throw new TypeError('sensitive bytes must use an ArrayBuffer-backed Uint8Array');
+    }
+    const generation = this.generation;
+    if (!generation || generation.closed || generation.childProcess !== this.childProcess
+      || !this._connected || !generation.sensitiveWriter || generation.sensitiveWriter.destroyed) {
+      throw new Error('sensitive byte pipe not available');
+    }
+    if (generation.sensitiveUsed) throw new Error('sensitive byte pipe was already used');
+    generation.sensitiveUsed = true;
+    const maxPayloadSize = this.options.sensitiveByteChannel?.maxPayloadSize;
+    if (maxPayloadSize === undefined || data.byteLength > maxPayloadSize) {
+      throw new Error('sensitive byte payload exceeds its configured limit');
+    }
+    if (!/^[A-Za-z0-9_-]{1,128}$/.test(requestId)) throw new Error('invalid sensitive request id');
+
+    const requestIdBytes = Buffer.from(requestId, 'ascii');
+    const header = Buffer.alloc(SENSITIVE_FRAME_HEADER_SIZE + requestIdBytes.byteLength);
+    header.write(SENSITIVE_FRAME_MAGIC, 0, 4, 'ascii');
+    header.writeUInt8(1, 4);
+    header.writeUInt8(0, 5);
+    header.writeUInt16BE(requestIdBytes.byteLength, 6);
+    header.writeBigUInt64BE(BigInt(data.byteLength), 8);
+    requestIdBytes.copy(header, SENSITIVE_FRAME_HEADER_SIZE);
+    const payload = Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+    try {
+      await this.writeSensitiveChunk(generation, header, false);
+      await this.writeSensitiveChunk(generation, payload, true);
+    } catch (error: unknown) {
+      this.destroySensitiveEndpoint(generation);
+      throw error;
+    }
+  }
+
   /**
    * Kill the child process without waiting for confirmation.
    */
@@ -338,6 +431,7 @@ export class StdioTransport extends plugins.events.EventEmitter implements IRust
     generation.disconnectPromise = disconnectPromise;
     generation.rejectDisconnect = rejectDisconnect;
     this._connected = false;
+    this.destroySensitiveEndpoint(generation);
     void disconnectPromise.then(
       () => {
         if (generation.disconnectPromise === disconnectPromise) {
@@ -364,6 +458,7 @@ export class StdioTransport extends plugins.events.EventEmitter implements IRust
       this.destroyOwnedStdioEndpoint(generation, 'stdin');
       this.destroyOwnedStdioEndpoint(generation, 'stdout');
       this.destroyOwnedStdioEndpoint(generation, 'stderr');
+      this.destroySensitiveEndpoint(generation);
       return disconnectPromise;
     }
 
@@ -486,6 +581,55 @@ export class StdioTransport extends plugins.events.EventEmitter implements IRust
     }
   }
 
+  private writeSensitiveChunk(
+    generation: IStdioTransportGeneration,
+    data: Uint8Array,
+    end: boolean,
+  ): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+      const writer = generation.sensitiveWriter;
+      if (!writer || writer.destroyed || generation.closed || this.generation !== generation) {
+        reject(new Error('sensitive byte pipe not available'));
+        return;
+      }
+      let settled = false;
+      const cleanup = (): void => {
+        writer.off('error', onError);
+        writer.off('close', onClose);
+      };
+      const settle = (error?: Error | null): void => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        if (error) reject(error);
+        else resolve();
+      };
+      const onError = (error: Error): void => settle(error);
+      const onClose = (): void => settle(new Error('sensitive byte pipe closed before write completion'));
+      writer.once('error', onError);
+      writer.once('close', onClose);
+      try {
+        if (end) writer.end(data, () => settle());
+        else writer.write(data, error => settle(error));
+      } catch (error: unknown) {
+        settle(this.toError(error, 'Failed to write sensitive byte pipe'));
+      }
+    });
+  }
+
+  private destroySensitiveEndpoint(generation: IStdioTransportGeneration): void {
+    const endpoint = generation.sensitiveWriter;
+    if (!endpoint || endpoint.destroyed) return;
+    try {
+      endpoint.destroy();
+    } catch (error: unknown) {
+      const endpointError = this.toError(error, 'Failed to close sensitive byte pipe');
+      generation.rejectDisconnect?.(endpointError);
+      this.options.logger.log('error', endpointError.message);
+      if (this.listenerCount('error') > 0) this.emit('error', endpointError);
+    }
+  }
+
   private toError(error: unknown, prefix: string): Error {
     return new Error(prefix + ': ' + this.getErrorMessage(error));
   }