fg-dynamic-component 2.0.0 → 4.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 | 4.0.0 | `fg-dynamic-component@^4.0.0` |
11
+ | 22.2.3 | 3.0.0 | `fg-dynamic-component@^3.0.0` |
10
12
  | 22.1.6 | 2.0.0 | `fg-dynamic-component@^2.0.0` |
11
13
  | 17.2.4 | 1.1.1 | `fg-dynamic-component@^1.1.1` |
12
14
  | 17.2.4 | 1.1.0 | `fg-dynamic-component@^1.1.0` |
@@ -121,6 +123,36 @@ class MyComponent {
121
123
 
122
124
  _NOTE:_ You can declare components to dynamically load in static and/or dynamic way using or not the FGDynamicService.
123
125
 
126
+ #### Scoped registry
127
+
128
+ `FGDynamicService` uses a global registry. When configurations are not fully trusted
129
+ (for example multi-tenant or plugin scenarios), create a scoped registry and pass it
130
+ to the component. Scoped registries are propagated to nested items as well:
131
+
132
+ ```ts
133
+ import { FGDynamicComponent, FGDynamicRegistry, FGDynamicService } from "fg-dynamic-component";
134
+
135
+ const registry: FGDynamicRegistry = FGDynamicService.createRegistry();
136
+ registry.register("MyDynamicComponent1", MyDynamicComponent1);
137
+
138
+ @Component({
139
+ selector: "my-component",
140
+ template: `<fg-dynamic [configuration]="configuration()" [registry]="registry" [typePolicy]="{ requireScopedRegistry: true }" />`,
141
+ imports: [FGDynamicComponent],
142
+ standalone: true
143
+ })
144
+ class MyComponent {
145
+ registry = registry;
146
+ configuration = signal({ type: "MyDynamicComponent1" });
147
+ }
148
+ ```
149
+
150
+ A configuration can only resolve component names that were explicitly registered in
151
+ the registry it receives. Names such as `constructor`, `__proto__` or `toString` are
152
+ never resolved from the registry prototype chain. For untrusted configurations,
153
+ `[typePolicy]="{ requireScopedRegistry: true }"` makes the component refuse to fall
154
+ back to the global registry.
155
+
124
156
  ### Inputs and Outputs
125
157
 
126
158
  You can pass `inputs` and `outputs` to your dynamic components:
@@ -162,10 +194,15 @@ class MyDynamicComponent1 {
162
194
  You can update your inputs passing expressions binding using a view model and they will trigger standard Angular's life-cycle hooks
163
195
  (of course you should consider which change detection strategy you are using).
164
196
 
197
+ Both classic `@Output() EventEmitter` and signal outputs created with
198
+ `output()` are supported. Output handlers receive `$event`; handlers are also
199
+ invoked when an output emits `null`/`undefined` (for example an
200
+ `EventEmitter<void>`).
201
+
165
202
  ```ts
166
203
  @Component({
167
204
  selector: 'my-component',
168
- template: `<fg-dynamic [configuration]="configuration()" [(viewModel)]="viewModel" />`,
205
+ template: `<fg-dynamic [configuration]="configuration()" [(viewModel)]="viewModel" [expressionPolicy]="{ allowedMethods: ['handleSomething'] }" />`,
169
206
  imports: [FGDynamicComponent],
170
207
  standalone: true
171
208
  })
@@ -176,10 +213,14 @@ class MyComponent {
176
213
  hello: '$vm().count % 2 === 0 ? $vm().message : \'Hello World!\''
177
214
  },
178
215
  outputs: {
179
- onSomething: '$vm.update(viewModel => { ...viewModel, message: $event, count: viewModel.count + 1 })'
216
+ onSomething: '$vm().handleSomething($event)'
180
217
  }
181
218
  } as IFGDynamicItem);
182
- viewModel = model({ message: 'Hello World!', count: 0 });
219
+ viewModel = model({
220
+ message: 'Hello World!',
221
+ count: 0,
222
+ handleSomething: (value: string) => { /* ... */ }
223
+ });
183
224
  }
184
225
 
185
226
  @Component({
@@ -209,7 +250,7 @@ class MyComponent {
209
250
  configuration = signal({
210
251
  type: MyDynamicComponent1,
211
252
  attributes: {
212
- "my-attribute": "attribute-value",
253
+ "data-my-attribute": "attribute-value",
213
254
  class: "some classes",
214
255
  disabled: "$vm().isDisabled"
215
256
  }
@@ -218,6 +259,24 @@ class MyComponent {
218
259
  }
219
260
  ```
220
261
 
262
+ > **Allowed attributes**
263
+ >
264
+ > Only a safe allowlist of attributes is applied: `id`, `class`, `name`, `role`,
265
+ > `title`, `tabindex`, `hidden`, `dir`, `lang`, `for`, `href`, `src`, the common
266
+ > form attributes (`disabled`, `readonly`, `required`, `placeholder`, …) and any
267
+ > `data-*` or `aria-*` attribute.
268
+ >
269
+ > Event handlers (`on*`), `style`, `srcdoc`, `formaction`, namespaced attributes
270
+ > and non-primitive values are ignored. `href` and `src` only accept `http`,
271
+ > `https`, `mailto`, `tel` and relative URLs, so `javascript:` URLs are blocked
272
+ > even when they come from an expression.
273
+ >
274
+ > Boolean attributes (`hidden`, `disabled`, `readonly`, `required`, `checked`,
275
+ > `selected`, `multiple`) follow HTML presence semantics: a truthy value adds
276
+ > the attribute, while `false`/`null`/`undefined` removes it (it is never
277
+ > written as `hidden="false"`). Attributes deleted from the configuration, or
278
+ > whose value becomes `null`, are removed from the element.
279
+
221
280
  ### Reactive Forms
222
281
 
223
282
  You can declaratively set attributes to activate model binding, form control status (enabled/disabled) and validations with your ControlValueAccessor components.
@@ -254,6 +313,107 @@ class MyComponent {
254
313
  }
255
314
  ```
256
315
 
316
+ > **Security note**
317
+ >
318
+ > `disabled` and the form validators are configured by the same configuration that
319
+ > renders the form. They are **UX-only**: a client can always bypass them. Never use
320
+ > them for authorization or as the only validation layer. Enforce permissions,
321
+ > required fields, ranges and formats again on the server.
322
+ >
323
+ > Control names are interpreted as dot/bracket paths into the view model. Paths that
324
+ > contain `__proto__`, `prototype` or `constructor` are rejected, so a configuration
325
+ > cannot pollute object prototypes or register such names in a `FormGroup`.
326
+ >
327
+ > Dotted names such as `data.firstName` are wired through nested `FormGroup`s, so
328
+ > `formGroup.get('data.firstName')` works and no `FormGroup` key contains a dot.
329
+ > By default the component never reuses pre-existing controls or nested groups:
330
+ > a bind to an existing control is ignored unless
331
+ > `[formControlPolicy]="{ allowExistingControls: true }"` is set. Controls created
332
+ > by this component are removed on destroy; reused controls are left intact.
333
+ > Use `[formControlPolicy]="{ allowedControlNames: ['data.firstName'] }"` to
334
+ > restrict which control names a configuration may bind. Changing the form group
335
+ > or the evaluated control name rebinds the control automatically.
336
+
337
+ ## Security
338
+
339
+ ### Expressions are interpreted, never evaluated
340
+
341
+ `inputs`, `outputs` and `attributes` values that contain `$vm` or `$event` are
342
+ evaluated by a small, self-contained interpreter. No `eval`, `new Function` or
343
+ other string-to-code primitive is used. The supported subset is:
344
+
345
+ - literals (`'text'`, `42`, `true`, `false`, `null`, `undefined`), arrays and objects;
346
+ - member access `$vm().name`, `$vm()['name']` and optional chaining `$vm().a?.b`;
347
+ - calls to native built-ins (`$vm().items.map(...)`, `.filter(...)`, `.join(...)`,
348
+ string methods such as `.slice(...)`/`.trim(...)`) and expression-bodied arrow
349
+ functions;
350
+ - unary, arithmetic, comparison, logical, nullish and ternary operators;
351
+ - array/object spread and arrow functions whose body returns an expression or
352
+ contains a `return` statement.
353
+
354
+ Anything else is ignored at runtime (a warning is printed only in development mode).
355
+ In particular globals (`window`, `fetch`, …), DOM host objects (`$event`,
356
+ `$event.target`, `document`, `localStorage`, `location`, …), assignments, `new`,
357
+ `this`, template literals, regular-expression literals and access to `__proto__`,
358
+ `prototype`, `constructor`, `caller`, `callee`, `arguments`, `call`, `apply` or
359
+ `bind` are rejected. Expressions are also limited in size, token count, nesting
360
+ depth and evaluation steps.
361
+
362
+ A value that contains neither `$vm` nor `$event` is used as a plain literal.
363
+
364
+ #### Expression policy (read-only by default)
365
+
366
+ Expressions are a capability boundary, not ordinary sandboxed user code. Custom
367
+ methods reachable from the view model are rejected by default; allow only the
368
+ methods a configuration actually needs:
369
+
370
+ ```ts
371
+ template: `<fg-dynamic [configuration]="configuration()" [expressionPolicy]="{ allowedMethods: ['save'] }" />`
372
+ // Or, only for configurations you fully trust:
373
+ template: `<fg-dynamic [configuration]="configuration()" [expressionPolicy]="{ allowCustomMethods: true }" />`
374
+ ```
375
+
376
+ `$vm()` remains available and returns the view model. `$vm.set` and `$vm.update`
377
+ are not exposed by default; enable view-model mutation explicitly with
378
+ `[expressionPolicy]="{ allowViewModelMutation: true }"`.
379
+
380
+ > Treat configurations as untrusted data unless they come from your own code.
381
+ > For multi-tenant/plugin scenarios prefer a scoped registry,
382
+ > `expressionPolicy.allowedMethods`, `formControlPolicy.allowedControlNames`,
383
+ > `[typePolicy]="{ requireScopedRegistry: true }"` and
384
+ > `[attributePolicy]="{ strict: true }"`.
385
+
386
+ #### Component type policy
387
+
388
+ A direct `type` may be an Angular component class or a registry name. Promise and
389
+ function loaders execute host code and are rejected by default; opt in with
390
+ `[typePolicy]="{ allowFunctionTypes: true }"`. `requireScopedRegistry` prevents an
391
+ untrusted configuration from falling back to the global registry.
392
+
393
+ ### Other hardening
394
+
395
+ - Attribute names/values are validated (see [Attributes](#attributes)) and URL
396
+ schemes are checked.
397
+ - `attributePolicy.strict` disables `id`, `class`, `for`, `href` and `src`
398
+ (`name` remains available because it also drives form wiring), which mitigates
399
+ DOM clobbering and UI-redress scenarios. Combine it with a Content Security
400
+ Policy for untrusted content.
401
+ - `pattern` validators are size-limited, reject nested/ambiguous quantifiers and
402
+ quantified alternations (e.g. `(a+)+`, `(\d+(?:\d+)?)+`, `(a|aa)+`), and clone
403
+ `RegExp` values without `g`/`y` so validation is not stateful. The ReDoS check is
404
+ a conservative heuristic, not a full regular-expression analyzer.
405
+ - Configuration trees are limited in depth, total node count and
406
+ `inputs`/`outputs`/`attributes` key count/length. Repeated references and cycles
407
+ are rejected before rendering.
408
+ - Native string builders (`repeat`, `padStart`, `padEnd`, `join`) are bounded to
409
+ avoid memory/CPU exhaustion.
410
+ - The component registry uses a `Map` and never resolves inherited properties
411
+ (`constructor`, `__proto__`, …). Prefer a scoped registry for untrusted
412
+ configurations.
413
+ - Angular component classes are never invoked as loader functions.
414
+ - Dev-mode diagnostics never include expression sources, configuration values or
415
+ raw error objects.
416
+
257
417
  ## Contributing
258
418
 
259
419
  You are welcome to contribute to this project.