@elliemae/microfe-common 2.23.6 → 2.25.0

package/dist/cjs/auditThrottler.js

@@ -0,0 +1,60 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var auditThrottler_exports = {};
+__export(auditThrottler_exports, {
+  AuditThrottler: () => AuditThrottler
+});
+module.exports = __toCommonJS(auditThrottler_exports);
+class AuditThrottler {
+  #logger;
+  #enabled;
+  #throttleMs;
+  #lastAudited = /* @__PURE__ */ new Map();
+  static DEFAULT_THROTTLE_MS = 1e4;
+  constructor(options) {
+    this.#logger = options.logger;
+    this.#enabled = options.enabled ?? true;
+    this.#throttleMs = options.throttleMs ?? AuditThrottler.DEFAULT_THROTTLE_MS;
+  }
+  get enabled() {
+    return this.#enabled;
+  }
+  /**
+   * Log a high-frequency operation. When audit is enabled and the throttle
+   * window allows it the payload is sent at `audit` level; otherwise `debug`.
+   * @param {string} key - dedup key for throttling (e.g. `invoke:loan.getField`)
+   * @param {LogRecord} payload - structured log payload
+   */
+  log(key, payload) {
+    if (!this.#enabled) {
+      this.#logger.debug(payload);
+      return;
+    }
+    if (this.#throttleMs > 0) {
+      const now = performance.now();
+      const last = this.#lastAudited.get(key);
+      if (last !== void 0 && now - last < this.#throttleMs) {
+        this.#logger.debug(payload);
+        return;
+      }
+      this.#lastAudited.set(key, now);
+    }
+    this.#logger.audit(payload);
+  }
+}

package/dist/cjs/index.js

@@ -18,6 +18,7 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var index_exports = {};
 __export(index_exports, {
+  AuditThrottler: () => import_auditThrottler.AuditThrottler,
   Event: () => import_event2.Event,
   MessageType: () => import_messageType.MessageType,
   ProxyEvent: () => import_event.ProxyEvent,
@@ -39,3 +40,4 @@ var import_scriptingObject = require("./scriptingObject.js");
 var import_messageType = require("./messageType.js");
 var import_scriptingObjectManager = require("./scriptingObjectManager.js");
 var import_proxy = require("./proxy.js");
+var import_auditThrottler = require("./auditThrottler.js");

package/dist/esm/auditThrottler.js

@@ -0,0 +1,40 @@
+class AuditThrottler {
+  #logger;
+  #enabled;
+  #throttleMs;
+  #lastAudited = /* @__PURE__ */ new Map();
+  static DEFAULT_THROTTLE_MS = 1e4;
+  constructor(options) {
+    this.#logger = options.logger;
+    this.#enabled = options.enabled ?? true;
+    this.#throttleMs = options.throttleMs ?? AuditThrottler.DEFAULT_THROTTLE_MS;
+  }
+  get enabled() {
+    return this.#enabled;
+  }
+  /**
+   * Log a high-frequency operation. When audit is enabled and the throttle
+   * window allows it the payload is sent at `audit` level; otherwise `debug`.
+   * @param {string} key - dedup key for throttling (e.g. `invoke:loan.getField`)
+   * @param {LogRecord} payload - structured log payload
+   */
+  log(key, payload) {
+    if (!this.#enabled) {
+      this.#logger.debug(payload);
+      return;
+    }
+    if (this.#throttleMs > 0) {
+      const now = performance.now();
+      const last = this.#lastAudited.get(key);
+      if (last !== void 0 && now - last < this.#throttleMs) {
+        this.#logger.debug(payload);
+        return;
+      }
+      this.#lastAudited.set(key, now);
+    }
+    this.#logger.audit(payload);
+  }
+}
+export {
+  AuditThrottler
+};

package/dist/esm/index.js

@@ -8,7 +8,9 @@ import {
   SecurityContext
 } from "./scriptingObjectManager.js";
 import { ScriptingObjectProxy, isScriptingObjectProxy } from "./proxy.js";
+import { AuditThrottler } from "./auditThrottler.js";
 export {
+  AuditThrottler,
   Event,
   MessageType,
   ProxyEvent,

package/dist/types/lib/auditThrottler.d.ts

@@ -0,0 +1,29 @@
+import type { Logger, LogRecord } from '@elliemae/pui-diagnostics';
+export type AuditThrottlerOptions = {
+    logger: Logger;
+    /** When `true`, high-frequency operations are logged at `audit` level. @default true */
+    enabled?: boolean;
+    /** Throttle window (ms). Same operation key is audited at most once per window. @default 10000 */
+    throttleMs?: number;
+};
+/**
+ * Controls whether high-frequency operations are logged at `audit` level
+ * (sent to Splunk) or `debug` level (local only).
+ *
+ * When enabled, a per-key throttle window prevents the same operation from
+ * flooding Splunk. Operations outside the window or with throttling disabled
+ * (`throttleMs === 0`) go straight to `audit`.
+ */
+export declare class AuditThrottler {
+    #private;
+    static readonly DEFAULT_THROTTLE_MS = 10000;
+    constructor(options: AuditThrottlerOptions);
+    get enabled(): boolean;
+    /**
+     * Log a high-frequency operation. When audit is enabled and the throttle
+     * window allows it the payload is sent at `audit` level; otherwise `debug`.
+     * @param {string} key - dedup key for throttling (e.g. `invoke:loan.getField`)
+     * @param {LogRecord} payload - structured log payload
+     */
+    log(key: string, payload: LogRecord): void;
+}

package/dist/types/lib/index.d.ts

@@ -10,5 +10,7 @@ export { MessageType } from './messageType.js';
 export type { EventListeners, Listener } from './common.js';
 export type { ISSFGuest, ConnectParam } from './guest.js';
 export { ScriptingObjectManager, SecurityContext, } from './scriptingObjectManager.js';
-export type { AddScriptingObjectParams, GetObjectParams, GuestContext, } from './scriptingObjectManager.js';
+export type { AddScriptingObjectParams, CallContext, CallerInfo, GetObjectParams, GuestContext, } from './scriptingObjectManager.js';
 export { ScriptingObjectProxy, isScriptingObjectProxy } from './proxy.js';
+export { AuditThrottler } from './auditThrottler.js';
+export type { AuditThrottlerOptions } from './auditThrottler.js';

package/dist/types/lib/scriptingObjectManager.d.ts

@@ -11,6 +11,41 @@ export type GuestContext = {
      */
     id: string;
 };
+/**
+ * identity and optional host-supplied metadata for a caller
+ * in the call chain.
+ */
+export type CallerInfo = GuestContext & {
+    /**
+     * arbitrary metadata the intermediate host associates with
+     * this guest (e.g. security role, tenant id, permissions).
+     * Supplied via the `metadata` option in loadGuest().
+     */
+    metadata?: Record<string, unknown>;
+};
+/**
+ * Context attached to scripting object method calls.
+ * `guest` identifies the direct caller (verified via sourceWin);
+ * `callChain` traces the full path from the original caller when
+ * the call is forwarded through intermediate host/guest layers.
+ *
+ * **Trust model**: `guest` is host-verified (derived from the
+ * message source window). `callChain` is self-reported by the
+ * intermediate guest and carries the same trust level as the
+ * direct caller — if you trust guest B, you can trust the
+ * callChain it supplies.
+ */
+export type CallContext = {
+    guest: GuestContext;
+    /**
+     * Ordered list of callers when a call is forwarded through
+     * intermediate guests (e.g. A hosts B hosts C, C calls a
+     * scripting object — callChain will be [{ id: "C" }]).
+     * Each entry may carry host-supplied metadata.
+     * Absent for direct (non-forwarded) calls.
+     */
+    callChain?: CallerInfo[];
+};
 /**
  * security context under which the guest application is running
  */

package/dist/types/lib/tests/auditThrottler.test.d.ts

@@ -0,0 +1 @@
+export {};