@cdk8s/awscdk-resolver 0.0.597 → 0.0.598

package/.jsii

@@ -7,7 +7,7 @@
     "url": "https://aws.amazon.com"
   },
   "bundled": {
-    "@aws-sdk/client-cloudformation": "^3.1066.0"
+    "@aws-sdk/client-cloudformation": "^3.1067.0"
   },
   "dependencies": {
     "aws-cdk-lib": "^2.195.0",
@@ -4082,6 +4082,6 @@
       "symbolId": "src/resolve:AwsCdkResolver"
     }
   },
-  "version": "0.0.597",
-  "fingerprint": "sUOAXLahEGejo7aHG0RTm1BS2duu6k7e27Evq2l3ICE="
+  "version": "0.0.598",
+  "fingerprint": "2gz2MUcZyEmURQQ8/PoLqVnf088E+kvVVQmKzfFLIFs="
 }

package/lib/resolve.js

@@ -61,5 +61,5 @@ class AwsCdkResolver {
 }
 exports.AwsCdkResolver = AwsCdkResolver;
 _a = JSII_RTTI_SYMBOL_1;
-AwsCdkResolver[_a] = { fqn: "@cdk8s/awscdk-resolver.AwsCdkResolver", version: "0.0.597" };
+AwsCdkResolver[_a] = { fqn: "@cdk8s/awscdk-resolver.AwsCdkResolver", version: "0.0.598" };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicmVzb2x2ZS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NyYy9yZXNvbHZlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7Ozs7O0FBQUEsaURBQTZDO0FBQzdDLDZCQUE2QjtBQUM3Qiw2Q0FBK0U7QUFJL0UsTUFBYSxjQUFjO0lBRWxCLE9BQU8sQ0FBQyxPQUEwQjtRQUV2QyxJQUFJLENBQUMsbUJBQUssQ0FBQyxZQUFZLENBQUMsT0FBTyxDQUFDLEtBQUssQ0FBQyxFQUFFLENBQUM7WUFDdkMsT0FBTztRQUNULENBQUM7UUFFRCxJQUFJLE9BQU8sT0FBTyxDQUFDLEtBQUssS0FBSyxRQUFRLEVBQUUsQ0FBQztZQUN0QywrREFBK0Q7WUFDL0QsbUJBQW1CO1lBQ25CLE1BQU0sSUFBSSxLQUFLLENBQUMsdUJBQXVCLE9BQU0sQ0FBQyxPQUFPLENBQUMsS0FBSyxDQUFDLHNCQUFzQixDQUFDLENBQUM7UUFDdEYsQ0FBQztRQUVELE1BQU0sTUFBTSxHQUFHLElBQUksQ0FBQyxVQUFVLENBQUMsT0FBTyxDQUFDLEtBQUssQ0FBQyxDQUFDO1FBQzlDLElBQUksQ0FBQztZQUNILE1BQU0sV0FBVyxHQUFHLElBQUksQ0FBQyxnQkFBZ0IsQ0FBQyxNQUFNLENBQUMsQ0FBQztZQUNsRCxPQUFPLENBQUMsWUFBWSxDQUFDLFdBQVcsQ0FBQyxDQUFDO1FBQ3BDLENBQUM7UUFBQyxPQUFPLEdBQUcsRUFBRSxDQUFDO1lBQ2IsMkVBQTJFO1lBQzNFLGtFQUFrRTtZQUNsRSwyRUFBMkU7WUFDM0UsK0VBQStFO1lBQy9FLCtDQUErQztZQUMvQyxPQUFPLENBQUMsWUFBWSxDQUFDLG9DQUFvQyxNQUFNLENBQUMsSUFBSSxDQUFDLElBQUksS0FBSyxHQUFHLEVBQUUsQ0FBQyxDQUFDO1FBQ3ZGLENBQUM7SUFFSCxDQUFDO0lBRU8sVUFBVSxDQUFDLEtBQWE7UUFFOUIsTUFBTSxlQUFlLEdBQVksRUFBRSxDQUFDO1FBRXBDLEtBQUssTUFBTSxLQUFLLElBQUksMEJBQVksQ0FBQyxhQUFhLENBQUMsS0FBSyxDQUFDLENBQUMsTUFBTSxFQUFFLENBQUM7WUFDN0QsSUFBSSx1QkFBUyxDQUFDLFdBQVcsQ0FBQyxLQUFLLENBQUMsRUFBRSxDQUFDO2dCQUNqQyxNQUFNLEtBQUssR0FBRyxtQkFBSyxDQUFDLEVBQUUsQ0FBQyxLQUFLLENBQUMsTUFBTSxDQUFDLENBQUM7Z0JBQ3JDLGVBQWUsQ0FBQyxJQUFJLENBQUMsS0FBSyxDQUFDLENBQUM7Z0JBQzVCLE1BQU0sTUFBTSxHQUFHLEtBQUssQ0FBQyxJQUFJLENBQUMsT0FBTyxFQUFFLENBQUMsTUFBTSxDQUFDLENBQUMsQ0FBQyxFQUFFLENBQUMsQ0FBQyxZQUFZLHVCQUFTLElBQUksQ0FBQyxDQUFDLEtBQUssS0FBSyxLQUFLLENBQUMsQ0FBQyxDQUFDLENBQWMsQ0FBQztnQkFDN0csa0ZBQWtGO2dCQUNsRix3REFBd0Q7Z0JBQ3hELElBQUksTUFBTTtvQkFBRSxPQUFPLE1BQU0sQ0FBQztZQUM1QixDQUFDO1FBQ0gsQ0FBQztRQUVELDZCQUE2QjtRQUM3Qiw2QkFBNkI7UUFDN0Isb0NBQW9DO1FBQ3BDLG9GQUFvRjtRQUNwRiwrREFBK0Q7UUFDL0QsTUFBTSxJQUFJLEtBQUssQ0FBQyxxQ0FBcUMsS0FBSyx1QkFBdUIsZUFBZSxDQUFDLEdBQUcsQ0FBQyxDQUFDLENBQUMsRUFBRSxDQUFDLENBQUMsQ0FBQyxTQUFTLENBQUMsQ0FBQyxJQUFJLENBQUMsR0FBRyxDQUFDLEdBQUcsQ0FBQyxDQUFDO0lBRXZJLENBQUM7SUFFTyxnQkFBZ0IsQ0FBQyxNQUFpQjtRQUV4QyxNQUFNLE1BQU0sR0FBRyxJQUFJLENBQUMsSUFBSSxDQUFDLFNBQVMsRUFBRSxJQUFJLEVBQUUsS0FBSyxFQUFFLHVCQUF1QixDQUFDLENBQUM7UUFDMUUsT0FBTyxJQUFJLENBQUMsS0FBSyxDQUFDLElBQUEsNEJBQVksRUFBQyxPQUFPLENBQUMsUUFBUSxFQUFFO1lBQy9DLE1BQU07WUFDTixtQkFBSyxDQUFDLEVBQUUsQ0FBQyxNQUFNLENBQUMsQ0FBQyxTQUFTO1lBQzFCLE1BQU0sQ0FBQyxJQUFJLENBQUMsRUFBRTtTQUNmLEVBQUUsRUFBRSxRQUFRLEVBQUUsT0FBTyxFQUFFLEtBQUssRUFBRSxDQUFDLE1BQU0sQ0FBQyxFQUFFLENBQUMsQ0FBQyxRQUFRLEVBQUUsQ0FBQyxJQUFJLEVBQUUsQ0FBQyxDQUFDO0lBRWhFLENBQUM7O0FBOURILHdDQWdFQyIsInNvdXJjZXNDb250ZW50IjpbImltcG9ydCB7IGV4ZWNGaWxlU3luYyB9IGZyb20gJ2NoaWxkX3Byb2Nlc3MnO1xuaW1wb3J0ICogYXMgcGF0aCBmcm9tICdwYXRoJztcbmltcG9ydCB7IFRva2VuLCBTdGFjaywgVG9rZW5pemF0aW9uLCBSZWZlcmVuY2UsIENmbk91dHB1dCB9IGZyb20gJ2F3cy1jZGstbGliJztcbmltcG9ydCB7IElSZXNvbHZlciwgUmVzb2x1dGlvbkNvbnRleHQgfSBmcm9tICdjZGs4cyc7XG5cblxuZXhwb3J0IGNsYXNzIEF3c0Nka1Jlc29sdmVyIGltcGxlbWVudHMgSVJlc29sdmVyIHtcblxuICBwdWJsaWMgcmVzb2x2ZShjb250ZXh0OiBSZXNvbHV0aW9uQ29udGV4dCkge1xuXG4gICAgaWYgKCFUb2tlbi5pc1VucmVzb2x2ZWQoY29udGV4dC52YWx1ZSkpIHtcbiAgICAgIHJldHVybjtcbiAgICB9XG5cbiAgICBpZiAodHlwZW9mIGNvbnRleHQudmFsdWUgIT09ICdzdHJpbmcnKSB7XG4gICAgICAvLyBzaG91bGQgYmUgb2sgYmVjYXVzZSB3ZSBvbmx5IHJlc29sdmUgQ2ZuT3V0cHV0IHZhbHVlcywgd2hpY2hcbiAgICAgIC8vIG11c3QgYmUgc3RyaW5ncy5cbiAgICAgIHRocm93IG5ldyBFcnJvcihgSW52YWxpZCB2YWx1ZSB0eXBlOiAke3R5cGVvZihjb250ZXh0LnZhbHVlKX0gKEV4cGVjdGVkICdzdHJpbmcnKWApO1xuICAgIH1cblxuICAgIGNvbnN0IG91dHB1dCA9IHRoaXMuZmluZE91dHB1dChjb250ZXh0LnZhbHVlKTtcbiAgICB0cnkge1xuICAgICAgY29uc3Qgb3V0cHV0VmFsdWUgPSB0aGlzLmZldGNoT3V0cHV0VmFsdWUob3V0cHV0KTtcbiAgICAgIGNvbnRleHQucmVwbGFjZVZhbHVlKG91dHB1dFZhbHVlKTtcbiAgICB9IGNhdGNoIChlcnIpIHtcbiAgICAgIC8vIGlmIGJvdGggY2RrOHMgYW5kIEFXUyBDREsgYXBwbGljYXRpb25zIGFyZSBkZWZpbmVkIHdpdGhpbiB0aGUgc2FtZSBmaWxlLFxuICAgICAgLy8gYSBjZGs4cyBzeW50aCBpcyBnb2luZyB0byBoYXBwZW4gYmVmb3JlIHRoZSBBV1MgQ0RLIGRlcGxveW1lbnQuXG4gICAgICAvLyBpbiB0aGlzIGNhc2Ugd2UgbXVzdCBzd2FsbG93IHRoZSBlcnJvciwgb3RoZXJ3aXNlIHRoZSBBV1MgQ0RLIGRlcGxveW1lbnRcbiAgICAgIC8vIHdvbid0IGJlIGFibGUgdG8gZ28gdGhyb3VnaC4gd2UgcmVwbGFjZSB0aGUgdmFsdWUgd2l0aCBzb21ldGhpbmcgdG8gaW5kaWNhdGVcbiAgICAgIC8vIHRoYXQgYSBmZXRjaGluZyBhdHRlbXB0IHdhcyBtYWRlIGFuZCBmYWlsZWQuXG4gICAgICBjb250ZXh0LnJlcGxhY2VWYWx1ZShgRmFpbGVkIGZldGNoaW5nIHZhbHVlIGZvciBvdXRwdXQgJHtvdXRwdXQubm9kZS5wYXRofTogJHtlcnJ9YCk7XG4gICAgfVxuXG4gIH1cblxuICBwcml2YXRlIGZpbmRPdXRwdXQodmFsdWU6IHN0cmluZykge1xuXG4gICAgY29uc3QgaW5zcGVjdGVkU3RhY2tzOiBTdGFja1tdID0gW107XG5cbiAgICBmb3IgKGNvbnN0IHRva2VuIG9mIFRva2VuaXphdGlvbi5yZXZlcnNlU3RyaW5nKHZhbHVlKS50b2tlbnMpIHtcbiAgICAgIGlmIChSZWZlcmVuY2UuaXNSZWZlcmVuY2UodG9rZW4pKSB7XG4gICAgICAgIGNvbnN0IHN0YWNrID0gU3RhY2sub2YodG9rZW4udGFyZ2V0KTtcbiAgICAgICAgaW5zcGVjdGVkU3RhY2tzLnB1c2goc3RhY2spO1xuICAgICAgICBjb25zdCBvdXRwdXQgPSBzdGFjay5ub2RlLmZpbmRBbGwoKS5maWx0ZXIoYyA9PiBjIGluc3RhbmNlb2YgQ2ZuT3V0cHV0ICYmIGMudmFsdWUgPT09IHZhbHVlKVswXSBhcyBDZm5PdXRwdXQ7XG4gICAgICAgIC8vIHdlIGRvbid0IHJlYWxseSBjYXJlIGlmIHRoZXJlIGFyZSBtb3JlIG91dHB1dHMgKHBvc3NpYmx5IGZyb20gZGlmZmVyZW50IHN0YWNrcylcbiAgICAgICAgLy8gdGhhdCBwb2ludCB0byB0aGUgc2FtZSB2YWx1ZS4gdGhlIGZpcnN0IHdpbGwgc3VmZmljZS5cbiAgICAgICAgaWYgKG91dHB1dCkgcmV0dXJuIG91dHB1dDtcbiAgICAgIH1cbiAgICB9XG5cbiAgICAvLyBUaGlzIGNhbiBoYXBwZW4gaWYgZWl0aGVyOlxuICAgIC8vIC0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tXG4gICAgLy8gIDEuIFVzZXIgZGlkbid0IGRlZmluZSBhbiBvdXRwdXQuXG4gICAgLy8gIDIuIE91dHB1dCB3YXMgZGVmaW5lZCBpbiBhIGRpZmZlcmVudCBzdGFjayB0aGFuIHRoZSB0b2tlbnMgY29tcHJpc2luZyBpdHMgdmFsdWUuXG4gICAgLy8gIDMuIE5vbmUgb2YgdGhlIHRva2VucyBjb21wcmlzaW5nIHRoZSB2YWx1ZSBhcmUgYSBSZWZlcmVuY2UuXG4gICAgdGhyb3cgbmV3IEVycm9yKGBVbmFibGUgdG8gZmluZCBvdXRwdXQgZGVmaW5lZCBmb3IgJHt2YWx1ZX0gKEluc3BlY3RlZCBzdGFja3M6ICR7aW5zcGVjdGVkU3RhY2tzLm1hcChzID0+IHMuc3RhY2tOYW1lKS5qb2luKCcsJyl9KWApO1xuXG4gIH1cblxuICBwcml2YXRlIGZldGNoT3V0cHV0VmFsdWUob3V0cHV0OiBDZm5PdXRwdXQpIHtcblxuICAgIGNvbnN0IHNjcmlwdCA9IHBhdGguam9pbihfX2Rpcm5hbWUsICcuLicsICdsaWInLCAnZmV0Y2gtb3V0cHV0LXZhbHVlLmpzJyk7XG4gICAgcmV0dXJuIEpTT04ucGFyc2UoZXhlY0ZpbGVTeW5jKHByb2Nlc3MuZXhlY1BhdGgsIFtcbiAgICAgIHNjcmlwdCxcbiAgICAgIFN0YWNrLm9mKG91dHB1dCkuc3RhY2tOYW1lLFxuICAgICAgb3V0cHV0Lm5vZGUuaWQsXG4gICAgXSwgeyBlbmNvZGluZzogJ3V0Zi04Jywgc3RkaW86IFsncGlwZSddIH0pLnRvU3RyaW5nKCkudHJpbSgpKTtcblxuICB9XG5cbn1cbiJdfQ==

package/node_modules/@aws-sdk/client-cloudformation/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aws-sdk/client-cloudformation",
   "description": "AWS SDK for JavaScript Cloudformation Client for Node.js, Browser and React Native",
-  "version": "3.1066.0",
+  "version": "3.1067.0",
   "scripts": {
     "build": "concurrently 'yarn:build:types' 'yarn:build:es' && yarn build:cjs",
     "build:cjs": "node ../../scripts/compilation/inline",

package/node_modules/@nodable/entities/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodable/entities",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "Entity parser for XML, HTML, External entites with security and NCR control",
   "main": "./src/index.js",
   "type": "module",
@@ -25,10 +25,13 @@
     "xml",
     "html",
     "entity",
+    "entities",
+    "stringify",
     "encode",
     "decode",
     "ncr",
     "security",
+    "safe",
     "performance"
   ],
   "author": "Amit Gupta (https://solothought.com)",

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/package.json

@@ -66,7 +66,7 @@
     "jsii-docgen": "^10.5.0",
     "jsii-pacmak": "^1.134.0",
     "jsii-rosetta": "^5",
-    "projen": "^0.99.71",
+    "projen": "^0.99.72",
     "ts-jest": "^27",
     "ts-node": "^10.9.2",
     "typescript": "^5.9.3"
@@ -77,7 +77,7 @@
     "constructs": "^10.3.0"
   },
   "dependencies": {
-    "@aws-sdk/client-cloudformation": "^3.1066.0"
+    "@aws-sdk/client-cloudformation": "^3.1067.0"
   },
   "bundledDependencies": [
     "@aws-sdk/client-cloudformation"
@@ -93,7 +93,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.0.597",
+  "version": "0.0.598",
   "jest": {
     "coverageProvider": "v8",
     "testMatch": [