fg-dynamic-component 3.0.0 → 5.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -7,6 +7,8 @@ Create an Angular standalone signals based dynamic components tree through a JSO
7
7
 
8
8
  | Angular | fg-dynamic-component | NPM package |
9
9
  | ------- | -------------------- | ----------------------------- |
10
+ | 22.2.3 | 5.0.0 | `fg-dynamic-component@^5.0.0` |
11
+ | 22.2.3 | 4.0.0 | `fg-dynamic-component@^4.0.0` |
10
12
  | 22.2.3 | 3.0.0 | `fg-dynamic-component@^3.0.0` |
11
13
  | 22.1.6 | 2.0.0 | `fg-dynamic-component@^2.0.0` |
12
14
  | 17.2.4 | 1.1.1 | `fg-dynamic-component@^1.1.1` |
@@ -49,7 +51,7 @@ FGDynamicService.registerComponent("MyDynamicComponent5", async () => (await imp
49
51
 
50
52
  @Component({
51
53
  selector: "my-component",
52
- template: `<fg-dynamic [configuration]="configuration()" />`
54
+ template: `<fg-dynamic [configuration]="configuration()" [typePolicy]="{ allowFunctionTypes: true }" />`
53
55
  })
54
56
  class MyComponent {
55
57
  configuration = signal({
@@ -78,6 +80,10 @@ class MyComponent {
78
80
  }
79
81
  ```
80
82
 
83
+ > Promise and function loaders execute host code. The examples above opt in with
84
+ > `[typePolicy]="{ allowFunctionTypes: true }"`; omit it when you only use direct
85
+ > component classes or registry names.
86
+
81
87
  #### Standalone API
82
88
 
83
89
  You may use `<fg-dynamic>` as a standalone component:
@@ -90,7 +96,7 @@ FGDynamicService.registerComponent("MyDynamicComponent5", async () => (await imp
90
96
 
91
97
  @Component({
92
98
  selector: "my-component",
93
- template: `<fg-dynamic [configuration]="configuration()" />`,
99
+ template: `<fg-dynamic [configuration]="configuration()" [typePolicy]="{ allowFunctionTypes: true }" />`,
94
100
  imports: [FGDynamicComponent],
95
101
  standalone: true
96
102
  })
@@ -120,6 +126,9 @@ class MyComponent {
120
126
  }
121
127
  ```
122
128
 
129
+ > Promise and function loaders execute host code. The standalone example above
130
+ > opts in with `[typePolicy]="{ allowFunctionTypes: true }"`.
131
+
123
132
  _NOTE:_ You can declare components to dynamically load in static and/or dynamic way using or not the FGDynamicService.
124
133
 
125
134
  #### Scoped registry
@@ -136,7 +145,7 @@ registry.register("MyDynamicComponent1", MyDynamicComponent1);
136
145
 
137
146
  @Component({
138
147
  selector: "my-component",
139
- template: `<fg-dynamic [configuration]="configuration()" [registry]="registry" />`,
148
+ template: `<fg-dynamic [configuration]="configuration()" [registry]="registry" [typePolicy]="{ requireScopedRegistry: true }" />`,
140
149
  imports: [FGDynamicComponent],
141
150
  standalone: true
142
151
  })
@@ -148,7 +157,9 @@ class MyComponent {
148
157
 
149
158
  A configuration can only resolve component names that were explicitly registered in
150
159
  the registry it receives. Names such as `constructor`, `__proto__` or `toString` are
151
- never resolved from the registry prototype chain.
160
+ never resolved from the registry prototype chain. For untrusted configurations,
161
+ `[typePolicy]="{ requireScopedRegistry: true }"` makes the component refuse to fall
162
+ back to the global registry.
152
163
 
153
164
  ### Inputs and Outputs
154
165
 
@@ -191,10 +202,15 @@ class MyDynamicComponent1 {
191
202
  You can update your inputs passing expressions binding using a view model and they will trigger standard Angular's life-cycle hooks
192
203
  (of course you should consider which change detection strategy you are using).
193
204
 
205
+ Both classic `@Output() EventEmitter` and signal outputs created with
206
+ `output()` are supported. Output handlers receive `$event`; handlers are also
207
+ invoked when an output emits `null`/`undefined` (for example an
208
+ `EventEmitter<void>`).
209
+
194
210
  ```ts
195
211
  @Component({
196
212
  selector: 'my-component',
197
- template: `<fg-dynamic [configuration]="configuration()" [(viewModel)]="viewModel" />`,
213
+ template: `<fg-dynamic [configuration]="configuration()" [(viewModel)]="viewModel" [expressionPolicy]="{ allowedMethods: ['handleSomething'] }" />`,
198
214
  imports: [FGDynamicComponent],
199
215
  standalone: true
200
216
  })
@@ -259,9 +275,19 @@ class MyComponent {
259
275
  > `data-*` or `aria-*` attribute.
260
276
  >
261
277
  > Event handlers (`on*`), `style`, `srcdoc`, `formaction`, namespaced attributes
262
- > and non-primitive values are ignored. `href` and `src` only accept `http`,
263
- > `https`, `mailto`, `tel` and relative URLs, so `javascript:` URLs are blocked
264
- > even when they come from an expression.
278
+ > and non-primitive values are ignored. `href` and `src` accept relative and
279
+ > same-origin URLs plus `mailto:` and `tel:`; cross-origin and protocol-relative
280
+ > URLs are rejected by default, so an untrusted configuration cannot exfiltrate
281
+ > view-model data by pointing an image or link at an attacker-controlled host.
282
+ > Opt into external URLs for trusted configurations with
283
+ > `[attributePolicy]="{ allowExternalUrls: true }"`. `javascript:` and `data:`
284
+ > URLs stay blocked even when they come from an expression.
285
+ >
286
+ > Boolean attributes (`hidden`, `disabled`, `readonly`, `required`, `checked`,
287
+ > `selected`, `multiple`) follow HTML presence semantics: a truthy value adds
288
+ > the attribute, while `false`/`null`/`undefined` removes it (it is never
289
+ > written as `hidden="false"`). Attributes deleted from the configuration, or
290
+ > whose value becomes `null`, are removed from the element.
265
291
 
266
292
  ### Reactive Forms
267
293
 
@@ -309,6 +335,16 @@ class MyComponent {
309
335
  > Control names are interpreted as dot/bracket paths into the view model. Paths that
310
336
  > contain `__proto__`, `prototype` or `constructor` are rejected, so a configuration
311
337
  > cannot pollute object prototypes or register such names in a `FormGroup`.
338
+ >
339
+ > Dotted names such as `data.firstName` are wired through nested `FormGroup`s, so
340
+ > `formGroup.get('data.firstName')` works and no `FormGroup` key contains a dot.
341
+ > By default the component never reuses pre-existing controls or nested groups:
342
+ > a bind to an existing control is ignored unless
343
+ > `[formControlPolicy]="{ allowExistingControls: true }"` is set. Controls created
344
+ > by this component are removed on destroy; reused controls are left intact.
345
+ > Use `[formControlPolicy]="{ allowedControlNames: ['data.firstName'] }"` to
346
+ > restrict which control names a configuration may bind. Changing the form group
347
+ > or the evaluated control name rebinds the control automatically.
312
348
 
313
349
  ## Security
314
350
 
@@ -320,28 +356,81 @@ other string-to-code primitive is used. The supported subset is:
320
356
 
321
357
  - literals (`'text'`, `42`, `true`, `false`, `null`, `undefined`), arrays and objects;
322
358
  - member access `$vm().name`, `$vm()['name']` and optional chaining `$vm().a?.b`;
323
- - calls such as `$vm().save($event)` and expression-bodied arrow functions
324
- (for example `$vm().items.map(item => item.id)`);
359
+ - calls to native built-ins (`$vm().items.map(...)`, `.filter(...)`, `.join(...)`,
360
+ string methods such as `.slice(...)`/`.trim(...)`) and expression-bodied arrow
361
+ functions;
325
362
  - unary, arithmetic, comparison, logical, nullish and ternary operators;
326
363
  - array/object spread and arrow functions whose body returns an expression or
327
364
  contains a `return` statement.
328
365
 
329
366
  Anything else is ignored at runtime (a warning is printed only in development mode).
330
- In particular globals (`window`, `fetch`, …), assignments, `new`, `this`, template
331
- literals, regular-expression literals and access to `__proto__`, `prototype`,
332
- `constructor`, `caller`, `callee` or `arguments` are rejected. Expressions are also
333
- limited in size, token count, nesting depth and evaluation steps.
367
+ In particular globals (`window`, `fetch`, …), DOM host objects (`$event`,
368
+ `$event.target`, `document`, `localStorage`, `location`, …), assignments, `new`,
369
+ `this`, template literals, regular-expression literals and access to `__proto__`,
370
+ `prototype`, `constructor`, `caller`, `callee`, `arguments`, `call`, `apply` or
371
+ `bind` are rejected. Expressions are also limited in size, token count, nesting
372
+ depth and evaluation steps.
334
373
 
335
374
  A value that contains neither `$vm` nor `$event` is used as a plain literal.
336
375
 
337
- > Expressions are configuration data, not sandboxed user code: a trusted
338
- > configuration can still call methods that exist on the view model. Only load
339
- > configurations from sources you trust.
376
+ #### Expression policy (read-only by default)
377
+
378
+ Expressions are a capability boundary, not ordinary sandboxed user code. Custom
379
+ methods reachable from the view model are rejected by default; allow only the
380
+ methods a configuration actually needs:
381
+
382
+ ```ts
383
+ template: `<fg-dynamic [configuration]="configuration()" [expressionPolicy]="{ allowedMethods: ['save'] }" />`
384
+ // Or, only for configurations you fully trust:
385
+ template: `<fg-dynamic [configuration]="configuration()" [expressionPolicy]="{ allowCustomMethods: true }" />`
386
+ ```
387
+
388
+ `$vm()` remains available and returns the view model. `$vm.set` and `$vm.update`
389
+ are not exposed by default; enable view-model mutation explicitly with
390
+ `[expressionPolicy]="{ allowViewModelMutation: true }"`.
391
+
392
+ `allowedMethods` entries are **receiver-scoped to the root view model**: the
393
+ string form allows `$vm().save()` but not `$vm().nested.save()`, so granting one
394
+ method name does not unlock every reachable object with the same name. When a
395
+ nested capability is intentional, use the descriptor form
396
+ `{ name: 'save', on: someObject }` (or `{ name: 'save', receiver: 'any' }` for a
397
+ fully trusted view model).
398
+
399
+ Arrow parameters cannot rebind the host identifiers `$vm`, `$event` or `$ev`, and
400
+ the method policy also covers coercion hooks (`toString`, `valueOf`,
401
+ `Symbol.toPrimitive`, `Symbol.isConcatSpreadable`) on both receivers and
402
+ arguments, so native string/array methods cannot be used to invoke host code.
403
+
404
+ > Treat configurations as untrusted data unless they come from your own code.
405
+ > For multi-tenant/plugin scenarios prefer a scoped registry,
406
+ > `expressionPolicy.allowedMethods`, `formControlPolicy.allowedControlNames`,
407
+ > `[typePolicy]="{ requireScopedRegistry: true }"` and
408
+ > `[attributePolicy]="{ strict: true }"` (leave `allowExternalUrls` disabled).
409
+
410
+ #### Component type policy
411
+
412
+ A direct `type` may be an Angular component class or a registry name. Promise and
413
+ function loaders execute host code and are rejected by default; opt in with
414
+ `[typePolicy]="{ allowFunctionTypes: true }"`. `requireScopedRegistry` prevents an
415
+ untrusted configuration from falling back to the global registry.
340
416
 
341
417
  ### Other hardening
342
418
 
343
419
  - Attribute names/values are validated (see [Attributes](#attributes)) and URL
344
420
  schemes are checked.
421
+ - `attributePolicy.strict` disables `id`, `class`, `for`, `href` and `src`
422
+ (`name` remains available because it also drives form wiring), which mitigates
423
+ DOM clobbering and UI-redress scenarios. Combine it with a Content Security
424
+ Policy for untrusted content.
425
+ - `pattern` validators are size-limited, reject nested/ambiguous quantifiers and
426
+ quantified alternations (e.g. `(a+)+`, `(\d+(?:\d+)?)+`, `(a|aa)+`), and clone
427
+ `RegExp` values without `g`/`y` so validation is not stateful. The ReDoS check is
428
+ a conservative heuristic, not a full regular-expression analyzer.
429
+ - Configuration trees are limited in depth, total node count and
430
+ `inputs`/`outputs`/`attributes` key count/length. Repeated references and cycles
431
+ are rejected before rendering.
432
+ - Native string builders (`repeat`, `padStart`, `padEnd`, `join`) are bounded to
433
+ avoid memory/CPU exhaustion.
345
434
  - The component registry uses a `Map` and never resolves inherited properties
346
435
  (`constructor`, `__proto__`, …). Prefer a scoped registry for untrusted
347
436
  configurations.