@push.rocks/smartrust 2.1.0 → 2.3.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,9 +78,16 @@ 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();
+    if (options.terminationGracePeriodMs !== undefined
+      && (!Number.isSafeInteger(options.terminationGracePeriodMs) || options.terminationGracePeriodMs < 0)) {
+      throw new RangeError('RustBridge terminationGracePeriodMs must be a non-negative safe integer');
+    }
     if (options.inheritedFileDescriptors) {
       for (const descriptor of options.inheritedFileDescriptors) {
         if (!Number.isSafeInteger(descriptor) || descriptor < 0) {
@@ -85,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) {
@@ -105,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,
@@ -133,7 +153,9 @@ 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,
       });
     });
@@ -147,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({
@@ -187,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> => {
@@ -449,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);
@@ -576,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`
@@ -593,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`));
@@ -603,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);
@@ -704,6 +932,7 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
         streaming.fail(error);
       }
     } finally {
+      this.regularRequestPreparations--;
       if (!reservationTransferred) {
         this.releasePendingRequestReservation(admissionReservation);
       }
@@ -747,7 +976,7 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
 
     const terminationPromise = (async (): Promise<void> => {
       if (transport) {
-        await transport.disconnectAndWait({ gracePeriodMs: optionsArg.gracePeriodMs });
+        await transport.disconnectAndWait({ gracePeriodMs: optionsArg.gracePeriodMs ?? this.options.terminationGracePeriodMs });
       } else if (activationPromise) {
         // No transport exists yet (for example, binary lookup is pending). The
         // stopping state prevents that activation from publishing a transport.
@@ -762,7 +991,7 @@ export class RustBridge<TCommands extends TCommandMap = TCommandMap> extends plu
 
       const lateTransport = this.transport;
       if (lateTransport && lateTransport !== transport) {
-        await lateTransport.disconnectAndWait({ gracePeriodMs: optionsArg.gracePeriodMs });
+        await lateTransport.disconnectAndWait({ gracePeriodMs: optionsArg.gracePeriodMs ?? this.options.terminationGracePeriodMs });
       }
 
       this.transport = null;
@@ -875,33 +1104,63 @@ 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,
+        requestId: response.id,
+        method: pending.method,
+      }),
+    });
+  }
+
   private settlePendingRequest(
     id: string,
     settlement: TPendingRequestSettlement,

package/ts/classes.rustbridgerequesterror.ts

@@ -7,6 +7,8 @@ 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 {