@push.rocks/smartrust 2.1.0 → 2.3.0

package/ts/classes.stdiotransport.ts

@@ -8,13 +8,18 @@ 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;
   logger: IRustBridgeLogger;
 }
 
@@ -32,6 +37,9 @@ interface IStdioTransportGeneration {
   sigtermAttempted: boolean;
   sigkillAttempted: boolean;
   sigtermError: Error | null;
+  sensitiveWriter: plugins.stream.Writable | null;
+  sensitiveUsed: boolean;
+  sensitiveError: Error | null;
 }
 
 /**
@@ -47,7 +55,21 @@ export class StdioTransport extends plugins.events.EventEmitter implements IRust
 
   constructor(options: IStdioTransportOptions) {
     super();
-    this.options = options;
+    if (options.terminationGracePeriodMs !== undefined
+      && (!Number.isSafeInteger(options.terminationGracePeriodMs) || options.terminationGracePeriodMs < 0)) {
+      throw new RangeError('StdioTransport terminationGracePeriodMs must be a non-negative safe integer');
+    }
+    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);
   }
 
@@ -55,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).
    */
@@ -76,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,
@@ -90,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: '',
@@ -104,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;
@@ -145,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) {
@@ -192,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);
       });
     });
 
@@ -279,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.
    */
@@ -305,7 +404,7 @@ export class StdioTransport extends plugins.events.EventEmitter implements IRust
   public disconnectAndWait(
     options: IRustTransportDisconnectOptions = {},
   ): Promise<void> {
-    const gracePeriodMs = options.gracePeriodMs ?? DEFAULT_DISCONNECT_GRACE_PERIOD_MS;
+    const gracePeriodMs = options.gracePeriodMs ?? this.options.terminationGracePeriodMs ?? DEFAULT_DISCONNECT_GRACE_PERIOD_MS;
     if (!Number.isSafeInteger(gracePeriodMs) || gracePeriodMs < 0) {
       throw new RangeError(
         'StdioTransport gracePeriodMs must be a non-negative safe integer',
@@ -332,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) {
@@ -358,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;
     }
 
@@ -480,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));
   }

package/ts/interfaces/config.ts

@@ -19,7 +19,8 @@ export interface IRustBridgeRequestOptions {
 export interface IRustBridgeTerminateOptions {
   /**
    * Time to allow an owned stdio child to exit after SIGTERM before SIGKILL.
-   * Zero requests immediate SIGKILL. Defaults to 5000 milliseconds.
+   * Zero requests immediate SIGKILL. Defaults to the bridge's
+   * terminationGracePeriodMs, or 5000 milliseconds when not configured.
    */
   gracePeriodMs?: number;
 }
@@ -60,10 +61,27 @@ export interface IRustBridgeOptions extends IBinaryLocatorOptions {
    * closes the caller's source descriptors.
    */
   inheritedFileDescriptors?: readonly number[];
+  /**
+   * Opt in to one owned, one-shot binary pipe for a sensitive request in each
+   * spawned stdio generation. The pipe is appended after caller-owned inherited
+   * descriptors, so their child descriptor numbers remain unchanged.
+   */
+  sensitiveByteChannel?: {
+    /** Maximum raw sensitive payload size accepted by the bridge. */
+    maxPayloadSize: number;
+  };
   /** Timeout for individual requests in ms (default: 30000) */
   requestTimeoutMs?: number;
   /** Timeout for the ready event during spawn in ms (default: 10000) */
   readyTimeoutMs?: number;
+  /**
+   * Default stdio SIGTERM-to-SIGKILL grace period in milliseconds, including
+   * automatic startup and stdin-failure cleanup (default: 5000).
+   * Must be a non-negative safe integer. Explicit terminate() options override
+   * it only before cleanup starts; concurrent cleanup keeps its first choice.
+   * Socket termination never signals the remote daemon.
+   */
+  terminationGracePeriodMs?: number;
   /** Additional environment variables for the child process */
   env?: Record<string, string>;
   /** Name of the ready event emitted by the Rust binary (default: 'ready') */

package/ts/interfaces/ipc.ts

@@ -5,6 +5,20 @@ export interface IManagementRequest {
   id: string;
   method: string;
   params: Record<string, any>;
+  /** Value-free metadata for an associated one-shot binary frame. */
+  sensitive?: IManagementSensitivePayload;
+}
+
+export interface IManagementSensitivePayload {
+  protocol: 'smartrust-sensitive-v1';
+  fileDescriptor: number;
+  byteLength: number;
+}
+
+export interface IManagementSensitiveAck {
+  protocol: 'smartrust-sensitive-v1';
+  consumed: true;
+  byteLength: number;
 }
 
 /**
@@ -16,6 +30,8 @@ export interface IManagementResponse {
   result?: any;
   error?: string;
   errorCode?: string;
+  /** Required after the receiver consumed the exact associated binary frame. */
+  sensitiveAck?: IManagementSensitiveAck;
 }
 
 /**

package/ts/interfaces/transport.ts

@@ -35,6 +35,12 @@ export interface IRustTransport extends plugins.events.EventEmitter {
   /** Write a string to the transport. Handles backpressure. */
   write(data: string): Promise<void>;
 
+  /** Child descriptor for the optional one-shot sensitive byte pipe. */
+  readonly sensitiveFileDescriptor?: number | null;
+
+  /** Write and close one correlated binary frame. Available only in stdio mode. */
+  writeSensitiveFrame?(requestId: string, data: Uint8Array<ArrayBuffer>): Promise<void>;
+
   /** Disconnect the transport. For stdio: kills the process. For socket: closes the connection. */
   disconnect(): void;
 

package/ts/plugins.ts

@@ -5,8 +5,9 @@ import * as childProcess from 'child_process';
 import * as events from 'events';
 import * as url from 'url';
 import * as net from 'net';
+import * as stream from 'stream';
 
-export { path, fs, childProcess, events, url, net };
+export { path, fs, childProcess, events, url, net, stream };
 
 // @push.rocks scope
 import * as smartpath from '@push.rocks/smartpath';