@cdklabs/cdk-ssm-documents 0.0.64 → 0.0.66

package/node_modules/@nodable/entities/src/EntityDecoder.js

@@ -5,6 +5,30 @@
 
 import { XML as DEFAULT_XML_ENTITIES } from "./entities.js"
 
+// ---------------------------------------------------------------------------
+// Entity hook action constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Action constants for `onExternalEntity` and `onInputEntity` hooks.
+ *
+ * Use these instead of raw strings to avoid typos:
+ *
+ * @example
+ * import EntityDecoder, { ENTITY_ACTION } from './EntityDecoder.js';
+ * const dec = new EntityDecoder({
+ *   onInputEntity: (name, value) => ENTITY_ACTION.BLOCK,
+ * });
+ */
+export const ENTITY_ACTION = Object.freeze({
+  /** Resolve and expand the entity normally. */
+  ALLOW: 'allow',
+  /** Silently skip this entity — it will not be registered. */
+  BLOCK: 'block',
+  /** Throw an error, aborting entity registration entirely. */
+  THROW: 'throw',
+});
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -169,6 +193,14 @@ export default class EntityDecoder {
    *   the effective action is max(onNCR, rangeMinimum).
    * @param {'remove'|'throw'} [options.ncr.nullNCR='remove']
    *   Action for U+0000 (null). 'allow' and 'leave' are clamped to 'remove' since null is never safe.
+   * @param {((name: string, value: string) => 'allow'|'block'|'throw')|null} [options.onExternalEntity=null]
+   *   Hook called when an external entity is registered via `setExternalEntities()` or
+   *   `addExternalEntity()`. Return `ENTITY_ACTION.ALLOW` to accept the entity,
+   *   `ENTITY_ACTION.BLOCK` to silently skip it, or `ENTITY_ACTION.THROW` to abort with an error.
+   * @param {((name: string, value: string) => 'allow'|'block'|'throw')|null} [options.onInputEntity=null]
+   *   Hook called when an input entity is registered via `addInputEntities()`. Return
+   *   `ENTITY_ACTION.ALLOW` to accept, `ENTITY_ACTION.BLOCK` to silently skip, or
+   *   `ENTITY_ACTION.THROW` to abort with an error.
    */
   constructor(options = {}) {
     this._limit = options.limit || {};
@@ -204,6 +236,43 @@ export default class EntityDecoder {
     this._ncrXmlVersion = ncrCfg.xmlVersion;
     this._ncrOnLevel = ncrCfg.onLevel;
     this._ncrNullLevel = ncrCfg.nullLevel;
+
+    // --- Registration hooks ---
+    /** @type {((name: string, value: string) => 'allow'|'block'|'throw')|null} */
+    this._onExternalEntity = typeof options.onExternalEntity === 'function'
+      ? options.onExternalEntity
+      : null;
+    /** @type {((name: string, value: string) => 'allow'|'block'|'throw')|null} */
+    this._onInputEntity = typeof options.onInputEntity === 'function'
+      ? options.onInputEntity
+      : null;
+  }
+
+  // -------------------------------------------------------------------------
+  // Private: registration hook dispatch
+  // -------------------------------------------------------------------------
+
+  /**
+   * Invoke a registration hook for a single entity name/value pair.
+   * Returns true when the entity should be accepted, false when it should be
+   * silently skipped (BLOCK), and throws when the hook returns THROW.
+   *
+   * @param {((name: string, value: string) => 'allow'|'block'|'throw')|null} hook
+   * @param {string} name
+   * @param {string} value
+   * @param {string} context  — used in error messages ('external' | 'input')
+   * @returns {boolean}  true = accept, false = skip
+   */
+  _applyRegistrationHook(hook, name, value, context) {
+    if (!hook) return true; // no hook → always accept
+    const action = hook(name, value);
+    if (action === ENTITY_ACTION.BLOCK) return false;
+    if (action === ENTITY_ACTION.THROW) {
+      throw new Error(
+        `[EntityDecoder] Registration of ${context} entity "&${name};" was rejected by hook`
+      );
+    }
+    return true; // ALLOW or any unknown return value → accept
   }
 
   // -------------------------------------------------------------------------
@@ -213,6 +282,9 @@ export default class EntityDecoder {
   /**
    * Replace the full set of persistent external entities.
    * All keys are validated — throws on invalid characters.
+   * If `onExternalEntity` is set, it is called once per entry; entries that
+   * return `ENTITY_ACTION.BLOCK` are silently omitted, `ENTITY_ACTION.THROW`
+   * aborts the whole call.
    * @param {Record<string, string | { regex?: RegExp, val: string }>} map
    */
   setExternalEntities(map) {
@@ -221,18 +293,34 @@ export default class EntityDecoder {
         validateEntityName(key);
       }
     }
-    this._externalMap = mergeEntityMaps(map);
+    if (!this._onExternalEntity) {
+      this._externalMap = mergeEntityMaps(map);
+      return;
+    }
+    // Hook present — resolve values first, then filter
+    const flat = mergeEntityMaps(map);
+    const filtered = Object.create(null);
+    for (const [name, value] of Object.entries(flat)) {
+      if (this._applyRegistrationHook(this._onExternalEntity, name, value, 'external')) {
+        filtered[name] = value;
+      }
+    }
+    this._externalMap = filtered;
   }
 
   /**
    * Add a single persistent external entity.
+   * If `onExternalEntity` is set it is called before the entity is stored;
+   * `ENTITY_ACTION.BLOCK` silently skips storage, `ENTITY_ACTION.THROW` raises.
    * @param {string} key
    * @param {string} value
    */
   addExternalEntity(key, value) {
     validateEntityName(key);
     if (typeof value === 'string' && value.indexOf('&') === -1) {
-      this._externalMap[key] = value;
+      if (this._applyRegistrationHook(this._onExternalEntity, key, value, 'external')) {
+        this._externalMap[key] = value;
+      }
     }
   }
 
@@ -243,12 +331,25 @@ export default class EntityDecoder {
   /**
    * Inject DOCTYPE entities for the current document.
    * Also resets per-document expansion counters.
+   * If `onInputEntity` is set it is called once per entry; entries returning
+   * `ENTITY_ACTION.BLOCK` are silently omitted, `ENTITY_ACTION.THROW` aborts.
    * @param {Record<string, string | { regx?: RegExp, regex?: RegExp, val: string }>} map
    */
   addInputEntities(map) {
     this._totalExpansions = 0;
     this._expandedLength = 0;
-    this._inputMap = mergeEntityMaps(map);
+    if (!this._onInputEntity) {
+      this._inputMap = mergeEntityMaps(map);
+      return;
+    }
+    const flat = mergeEntityMaps(map);
+    const filtered = Object.create(null);
+    for (const [name, value] of Object.entries(flat)) {
+      if (this._applyRegistrationHook(this._onInputEntity, name, value, 'input')) {
+        filtered[name] = value;
+      }
+    }
+    this._inputMap = filtered;
   }
 
   // -------------------------------------------------------------------------

package/node_modules/@nodable/entities/src/index.d.ts

@@ -5,6 +5,50 @@
 /** A function-based entity replacement value (used for numeric refs). */
 export type EntityValFn = (match: string, captured: string, ...rest: unknown[]) => string;
 
+// ---------------------------------------------------------------------------
+// Entity registration hook
+// ---------------------------------------------------------------------------
+
+/**
+ * Actions returned by `onExternalEntity` / `onInputEntity` hooks.
+ * Use the `ENTITY_ACTION` constant object instead of raw strings to avoid typos.
+ *
+ * - `'allow'` — register and expand the entity normally
+ * - `'block'` — silently skip the entity (not registered, treated as unknown)
+ * - `'throw'` — abort registration with an error
+ */
+export type EntityHookAction = 'allow' | 'block' | 'throw';
+
+/**
+ * Immutable constant bag for entity registration hook return values.
+ *
+ * @example
+ * import { ENTITY_ACTION } from '@nodable/entities';
+ * const dec = new EntityDecoder({
+ *   onInputEntity: (_name, _value) => ENTITY_ACTION.BLOCK,
+ * });
+ */
+export const ENTITY_ACTION: Readonly<{
+  /** Register and expand the entity normally. */
+  ALLOW: 'allow';
+  /** Silently skip this entity — it will not be registered. */
+  BLOCK: 'block';
+  /** Throw an error, aborting entity registration. */
+  THROW: 'throw';
+}>;
+
+/**
+ * Callback signature for `onExternalEntity` and `onInputEntity` hooks.
+ *
+ * Called once per entity **at registration time** (not at decode time).
+ * Return `ENTITY_ACTION.ALLOW` (or `'allow'`) to accept, `ENTITY_ACTION.BLOCK`
+ * to silently skip, or `ENTITY_ACTION.THROW` to raise an error.
+ *
+ * @param name  — the entity name without `&` / `;`, e.g. `"brand"`
+ * @param value — the resolved string value after any `{regex,val}` unwrapping
+ */
+export type EntityRegistrationHook = (name: string, value: string) => EntityHookAction;
+
 // ---------------------------------------------------------------------------
 // Encoder options
 // ---------------------------------------------------------------------------
@@ -191,6 +235,39 @@ export interface EntityDecoderOptions {
    * Numeric Character Reference (NCR) policy.
    */
   ncr?: EntityDecoderNCROptions;
+
+  /**
+   * Hook called once **at registration time** for each entity passed to
+   * `setExternalEntities()` or `addExternalEntity()`.
+   *
+   * - `'allow'` (or `ENTITY_ACTION.ALLOW`) — register the entity normally (default)
+   * - `'block'` (or `ENTITY_ACTION.BLOCK`) — silently skip; the entity is not stored
+   * - `'throw'` (or `ENTITY_ACTION.THROW`) — abort registration with an `Error`
+   *
+   * The hook receives the entity name (without `&`/`;`) and the resolved string
+   * value. It is **not** called during `decode()` — only when entities are added.
+   *
+   * @example
+   * const dec = new EntityDecoder({
+   *   onExternalEntity: (name, value) =>
+   *     DANGEROUS_NAMES.has(name) ? ENTITY_ACTION.BLOCK : ENTITY_ACTION.ALLOW,
+   * });
+   */
+  onExternalEntity?: EntityRegistrationHook | null;
+
+  /**
+   * Hook called once **at registration time** for each entity passed to
+   * `addInputEntities()`.
+   *
+   * Follows the same `'allow' | 'block' | 'throw'` contract as `onExternalEntity`.
+   *
+   * @example
+   * const dec = new EntityDecoder({
+   *   // Block all input / DOCTYPE entities unconditionally
+   *   onInputEntity: () => ENTITY_ACTION.BLOCK,
+   * });
+   */
+  onInputEntity?: EntityRegistrationHook | null;
 }
 
 // ---------------------------------------------------------------------------

package/node_modules/@nodable/entities/src/index.js

@@ -6,7 +6,7 @@
 
  */
 
-export { default as EntityDecoder } from './EntityDecoder.js';
+export { default as EntityDecoder, ENTITY_ACTION } from './EntityDecoder.js';
 export {
   COMMON_HTML,
   XML,

package/node_modules/@smithy/core/dist-cjs/index.js

@@ -1,9 +1,9 @@
-'use strict';
-
-var transport = require('@smithy/core/transport');
-var protocols = require('@smithy/core/protocols');
-var types = require('@smithy/types');
-var client = require('@smithy/core/client');
+const { getSmithyContext } = require("@smithy/core/transport");
+exports.getSmithyContext = getSmithyContext;
+const { HttpRequest } = require("@smithy/core/protocols");
+const { requestBuilder } = require("@smithy/core/protocols");
+exports.requestBuilder = requestBuilder;
+const { HttpApiKeyAuthLocation } = require("@smithy/types");
 
 const resolveAuthOptions = (candidateAuthOptions, authSchemePreference) => {
     if (!authSchemePreference || authSchemePreference.length === 0) {
@@ -38,7 +38,7 @@ const httpAuthSchemeMiddleware = (config, mwOptions) => (next, context) => async
     const authSchemePreference = config.authSchemePreference ? await config.authSchemePreference() : [];
     const resolvedOptions = resolveAuthOptions(options, authSchemePreference);
     const authSchemes = convertHttpAuthSchemesToMap(config.httpAuthSchemes);
-    const smithyContext = client.getSmithyContext(context);
+    const smithyContext = getSmithyContext(context);
     const failureReasons = [];
     for (const option of resolvedOptions) {
         const scheme = authSchemes.get(option.schemeId);
@@ -106,10 +106,10 @@ const defaultErrorHandler = (signingProperties) => (error) => {
 };
 const defaultSuccessHandler = (httpResponse, signingProperties) => { };
 const httpSigningMiddleware = (config) => (next, context) => async (args) => {
-    if (!protocols.HttpRequest.isInstance(args.request)) {
+    if (!HttpRequest.isInstance(args.request)) {
         return next(args);
     }
-    const smithyContext = client.getSmithyContext(context);
+    const smithyContext = getSmithyContext(context);
     const scheme = smithyContext.selectedHttpAuthScheme;
     if (!scheme) {
         throw new Error(`No HttpAuthScheme was selected: unable to sign request`);
@@ -228,11 +228,11 @@ class HttpApiKeyAuthSigner {
         if (!identity.apiKey) {
             throw new Error("request could not be signed with `apiKey` since the `apiKey` is not defined");
         }
-        const clonedRequest = protocols.HttpRequest.clone(httpRequest);
-        if (signingProperties.in === types.HttpApiKeyAuthLocation.QUERY) {
+        const clonedRequest = HttpRequest.clone(httpRequest);
+        if (signingProperties.in === HttpApiKeyAuthLocation.QUERY) {
             clonedRequest.query[signingProperties.name] = identity.apiKey;
         }
-        else if (signingProperties.in === types.HttpApiKeyAuthLocation.HEADER) {
+        else if (signingProperties.in === HttpApiKeyAuthLocation.HEADER) {
             clonedRequest.headers[signingProperties.name] = signingProperties.scheme
                 ? `${signingProperties.scheme} ${identity.apiKey}`
                 : identity.apiKey;
@@ -249,7 +249,7 @@ class HttpApiKeyAuthSigner {
 
 class HttpBearerAuthSigner {
     async sign(httpRequest, identity, signingProperties) {
-        const clonedRequest = protocols.HttpRequest.clone(httpRequest);
+        const clonedRequest = HttpRequest.clone(httpRequest);
         if (!identity.token) {
             throw new Error("request could not be signed with `token` since the `token` is not defined");
         }
@@ -320,8 +320,6 @@ const memoizeIdentityProvider = (provider, isExpired, requiresRefresh) => {
     };
 };
 
-exports.getSmithyContext = transport.getSmithyContext;
-exports.requestBuilder = protocols.requestBuilder;
 exports.DefaultIdentityProviderConfig = DefaultIdentityProviderConfig;
 exports.EXPIRATION_MS = EXPIRATION_MS;
 exports.HttpApiKeyAuthSigner = HttpApiKeyAuthSigner;