spiderly 19.8.9 → 19.8.10

package/agent/docs/angular-customization/references/controls.generated.md

@@ -12,7 +12,7 @@ Every control also accepts the shared `BaseControl` inputs: `control`, `controlV
 | `spiderly-checkbox` | `SpiderlyCheckboxComponent` | `fakeLabel`, `initializeToFalse`, `inlineLabel` |
 | `spiderly-colorpicker` | `SpiderlyColorPickerComponent` | `showInputTextField` |
 | `spiderly-dropdown` | `SpiderlyDropdownComponent` | `isBooleanPicker` |
-| `spiderly-editor` | `SpiderlyEditorComponent` | `uploadImageMethod`, `objectId` |
+| `spiderly-editor` | `SpiderlyEditorComponent` | `uploadImageMethod`, `objectId`, `acceptedFileTypes` |
 | `spiderly-file` | `SpiderlyFileComponent` | `objectId`, `fileData`, `acceptedFileTypes`, `required`, `multiple`, `isUrlFileData`, `imageWidth`, `imageHeight`, `maxFileSize`, `files` |
 | `spiderly-markdown` | `SpiderlyMarkdownComponent` | `uploadImageMethod`, `objectId` |
 | `spiderly-multiautocomplete` | `SpiderlyMultiAutocompleteComponent` | — |

package/agent/docs/authorization/index.md

@@ -243,18 +243,21 @@ public virtual async Task AuthorizeProductDeleteAndThrow(long id)
 
 ## Registering Principal Kinds
 
-Register each principal kind in `AddAppServices` so authorization can resolve the current principal.
-A single-principal app registers just `User`; the kind-dispatched authorization then resolves it
-without a `principal_kind` claim (it is the sole, default kind):
+The `User` principal kind is registered for you by `spiderly.AddSecurity<User, UserExternalLogin, AuthorizationService>(…)`
+in `Startup.cs` — a single-principal app needs nothing more. The kind-dispatched authorization then resolves
+`User` without a `principal_kind` claim (it is the sole, default kind).
+
+To add **another** principal kind (a machine/service account, …), register it with `AddSpiderlyPrincipal<T>`
+in `AddAppServices`:
 
 ```csharp
-services.AddSpiderlyPrincipal<User>("User");
-// Add a line per additional principal kind, e.g.:
-// services.AddSpiderlyPrincipal<ServiceAccount>("ServiceAccount");
+// The User kind is already registered by AddSecurity — add a line per *additional* kind:
+services.AddSpiderlyPrincipal<ServiceAccount>("ServiceAccount");
 ```
 
 Each kind is any entity implementing `ISecurityPrincipal` with its own `Roles` into the shared
-Role/Permission catalog. (`spiderly init` scaffolds the `User` registration for you.)
+Role/Permission catalog. API keys have a dedicated sub-builder — `AddSecurity<…>(s => s.AddApiKeys<ApiKey>())` —
+which registers the `ApiKey` kind and its auth scheme together (see the API-keys docs).
 
 ## Checking Permissions in Custom Code
 

package/agent/docs/backend-hooks/index.md

@@ -107,7 +107,8 @@ public virtual async Task OnBefore{Property}BlobFor{Entity}UploadIsAuthorized(
 public virtual async Task<byte[]> OnBefore{Property}BlobFor{Entity}IsUploaded(
     Stream stream, IFormFile file, {IdType} id) { }
 
-// Image-specific hooks (called by OnBefore*IsUploaded for image/* content types)
+// Image-specific hooks (called by OnBefore*IsUploaded for raster image content
+// types only — Helper.IsOptimizableImage; SVG/video/PDF pass through raw)
 public virtual async Task ValidateImageFor{Property}Of{Entity}(
     Stream stream, IFormFile file, {IdType} id) { }
 public virtual async Task<byte[]> OptimizeImageFor{Property}Of{Entity}(

package/agent/docs/entity-design/references/attributes.generated.md

@@ -5,7 +5,7 @@
 
 | Attribute | Target | Description |
 | --- | --- | --- |
-| `[AcceptedFileTypes]` | Property | Specifies the accepted file types for a blob property. When not applied, the file upload defaults to accepting images only (image/*). Use this attribute alongside any StorageAttribute subclass (e.g. [S3PublicStorage]) for non-image uploads (PDFs, Excel files, etc.). |
+| `[AcceptedFileTypes]` | Property | Specifies the accepted file types for a blob property. Mandatory on every blob property (build error SPIDERLY014 when missing) alongside any StorageAttribute subclass (e.g. [S3PublicStorage]). Entry semantics: — MIME entries ("image/png") are enforced server-side (declared type whitelist + content inspection) and passed to the UI file picker. — Type wildcards ("image/*") match any declared type with that prefix. — Extension entries (".pdf" — leading dot, no '/') only widen the UI file picker; the server validates the MIME entries, so always pair an extension with its MIME type. — "image/svg+xml" is validated structurally (XML with an <svg> root, active content rejected) since SVG has no magic bytes, and is uploaded as-is (no ImageSharp optimization). |
 | `[AuthGuard]` | Class, Method | Provides authentication protection for API endpoints by validating JWT tokens in the request. |
 | `[CascadeDelete]` | Property | Implements cascade delete behavior in many-to-one relationships. When the referenced entity is deleted, all entities that reference it will automatically be deleted as well. This attribute is useful when: - Child entities should not exist without their parent |
 | `[ComplexManyToManyList]` | Property | Generates an editable list UI for complex many-to-many relationships (junction tables with additional fields). Shows ALL entities from the "other side" with editable junction fields. No add/remove/reorder controls. Warning: This loads all "other side" entities into the form. Suitable for small sets (e.g., 3 warehouses), not for large sets (e.g., thousands of entities). |

package/agent/docs/file-storage/index.md

@@ -154,14 +154,28 @@ Generated methods per blob property:
 ```
 1. Upload{Property}For{Entity}(IFormFile file)         ← Controller endpoint
 2.   → OnBefore{Property}BlobFor{Entity}UploadIsAuthorized(file, id)
-3.   → OnBefore{Property}BlobFor{Entity}IsUploaded(stream, file, id)
-4.       → For image/* content types:
-5.           → ValidateImageFor{Property}Of{Entity}(stream, file, id)
-6.           → OptimizeImageFor{Property}Of{Entity}(stream, file, id)
-7.   → storageService.UploadFileAsync(...)            ← resolved per [*Storage] attribute
-8.   → Returns file key/URL (semantics depend on the adapter)
+3.   → Helper.ValidateFileSize + Helper.ValidateFileSignature (whitelist + content inspection)
+4.   → OnBefore{Property}BlobFor{Entity}IsUploaded(stream, file, id)
+5.       → For raster image content types (Helper.IsOptimizableImage — image/* except SVG):
+6.           → ValidateImageFor{Property}Of{Entity}(stream, file, id)
+7.           → OptimizeImageFor{Property}Of{Entity}(stream, file, id)
+8.       → Everything else (SVG, video, PDF, …) passes through raw
+9.   → storageService.UploadFileAsync(...)            ← resolved per [*Storage] attribute
+10.  → Returns file key/URL (semantics depend on the adapter)
 ```
 
+### File-type validation semantics
+
+`Helper.ValidateFileSignature` enforces the `[AcceptedFileTypes]` whitelist server-side:
+
+- MIME entries (`"image/png"`) must match the declared content type — exactly, or by prefix for type wildcards (`"image/*"`).
+- Extension entries (`".pdf"` — leading dot, no `/`) only widen the UI file picker; always pair them with the MIME type.
+- Binary types are then verified against the stream's **magic bytes** (Mime-Detective), so a spoofed `Content-Type` header is rejected.
+- `image/svg+xml` has no magic bytes — it is validated **structurally** instead: must parse as XML with an `<svg>` root, and active content (script elements, `on*` event attributes, `javascript:` hrefs, `foreignObject`) is rejected. SVG also bypasses ImageSharp optimization (step 5) and uploads as-is.
+- Failures throw `BusinessException` (HTTP 400, localized message shown to the user — keys `FileTypeNotAllowed`, `FileContentDoesNotMatchType`, `FileContainsActiveContent`, `FileIsEmpty`, `FileSizeExceeded`).
+
+Inline editor image uploads (`Upload{Property}ImageFor{Entity}` for `[Editor]`/`[Markdown]` + `[S3PublicStorage]` properties) run the same size + type validation against the property's `[AcceptedFileTypes]`. Raster images are optimized and return their pixel dimensions; SVG uploads as-is and its dimensions are best-effort (`Helper.GetSvgDimensions`: root width/height, then viewBox, else `(0, 0)` — the editor omits width/height attributes when unknown).
+
 On entity save (Update/Insert):
 
 ```
@@ -184,8 +198,8 @@ public override async Task OnBeforeMainImageBlobForProductUploadIsAuthorized(
 public override async Task<byte[]> OnBeforeMainImageBlobForProductIsUploaded(
     Stream stream, IFormFile file, long id)
 {
-    // For images: validate then optimize
-    if (file.ContentType.StartsWith("image/"))
+    // For raster images: validate then optimize (SVG/video/PDF pass through raw)
+    if (Helper.IsOptimizableImage(file.ContentType))
     {
         await ValidateImageForMainImageOfProduct(stream, file, id);
         stream.Position = 0;
@@ -233,7 +247,7 @@ public static async Task ValidateImageDimensions(
 )
 ```
 
-Throws `SecurityViolationException` if dimensions don't match exactly.
+Throws `BusinessException` (localized, shown to the user) if dimensions don't match exactly.
 
 ## Cleanup methods
 

package/agent/skills/api-keys/SKILL.md

@@ -20,8 +20,8 @@ Modeling the key as its own `ISecurityPrincipal` (rather than "resolve to the ow
 
 ## Step 0 — Prerequisites
 
-1. **Spiderly version** — confirm the compiled mechanism is present. It must expose `Spiderly.Security.Authentication.IApiKeyAuthenticator`, `AddSpiderlyApiKeyAuthentication`, and `PrincipalKinds.ApiKey`. If a `using Spiderly.Security.Authentication;` doesn't resolve those, the app is on too old a Spiderly version — upgrade first (see the `spiderly-upgrade` skill).
-2. **The app must already use Spiderly auth** — it registers a human principal (`AddSpiderlyPrincipal<User>(PrincipalKinds.User)`) and calls `spiderly.AddAuthentication()`. API keys add a *second* principal kind alongside it.
+1. **Spiderly version** — confirm the compiled mechanism is present. It must expose `Spiderly.Security.Authentication.IApiKeyAuthenticator`, the `AddApiKeys<TApiKey>()` sub-builder on `SpiderlySecurityBuilder`, and `PrincipalKinds.ApiKey`. If those don't resolve, the app is on too old a Spiderly version — upgrade first (see the `spiderly-upgrade` skill).
+2. **The app must already use Spiderly auth** — its `Startup.cs` calls `spiderly.AddSecurity<User, UserExternalLogin, AuthorizationService>(…)`, which registers the human `User` principal and enables authentication. API keys add a *second* principal kind alongside it.
 
 Decide with the user up front: **do they want an admin UI** to manage keys, or **API/agent-only** (drive generation via the REST endpoints / a management skill)? The backend is identical either way; the UI is the optional Step 8.
 
@@ -90,7 +90,7 @@ Add the inverse M2M nav `public virtual List<ApiKey> ApiKeys { get; } = new(); /
 
 The framework ships `DefaultApiKeyAuthenticator<TApiKey>`, which does the hash→active-id lookup over your `ApiKey` entity generically (it reads it via the `IApiKey` interface, so it stays decoupled from your namespace). You get it for free from the Step 4 registration — there is **no authenticator to hand-write**.
 
-Only implement your own `IApiKeyAuthenticator` for a non-standard lookup (e.g. an external key store). If you do, register it **before** `AddSpiderlyApiKeyAuthentication<ApiKey>()` — the framework adds the default with `TryAdd`, so your registration wins.
+Only implement your own `IApiKeyAuthenticator` for a non-standard lookup (e.g. an external key store). If you do, register it **before** the `AddApiKeys<ApiKey>()` call (Step 4) — the framework adds the default with `TryAdd`, so your registration wins.
 
 ## Step 3 — `ApiKeyService` hooks (generate + hash + show-once)
 
@@ -149,16 +149,15 @@ public class ApiKeyService : ApiKeyServiceGenerated
 
 `ApiKeyHelper` is `Spiderly.Security.Authentication`. If the app's authorization service has a different class name, inject that.
 
-## Step 4 — Register the principal + the auth scheme
+## Step 4 — Register the key (API-keys sub-builder)
 
-In the app's service-registration (where `AddSpiderlyPrincipal<User>` is called, **after** `AddSpiderly(...)`):
+Pass an `s => s.AddApiKeys<ApiKey>()` configurator to the existing `spiderly.AddSecurity<…>(…)` call in `Startup.cs`:
 
 ```csharp
-services.AddSpiderlyPrincipal<ApiKey>(PrincipalKinds.ApiKey);
-services.AddSpiderlyApiKeyAuthentication<ApiKey>();
+spiderly.AddSecurity<User, UserExternalLogin, AuthorizationService>(s => s.AddApiKeys<ApiKey>());
 ```
 
-`AddSpiderlyApiKeyAuthentication` registers the `ApiKey` scheme **and** a forwarding policy scheme set as the default — so `X-Api-Key` requests route to the key handler and everything else to JWT, with no per-endpoint `[Authorize(AuthenticationSchemes=...)]` churn. Registering a second principal kind makes the app multi-principal; the JWT login already stamps `PrincipalKinds.User`, the key handler stamps `PrincipalKinds.ApiKey`, so both satisfy the now-required `principal_kind` claim.
+`AddApiKeys<ApiKey>()` registers the `ApiKey` principal kind **and** the authentication scheme in one call — the `ApiKey` scheme plus a forwarding policy scheme set as the default, so `X-Api-Key` requests route to the key handler and everything else to JWT, with no per-endpoint `[Authorize(AuthenticationSchemes=...)]` churn. Registering a second principal kind makes the app multi-principal; the JWT login already stamps `PrincipalKinds.User`, the key handler stamps `PrincipalKinds.ApiKey`, so both satisfy the now-required `principal_kind` claim.
 
 ## Step 5 — The issuance guard (authorization service)
 

package/agent/skills/verify-ui/SKILL.md

@@ -10,7 +10,25 @@ The Spiderly admin panel sits entirely behind a passwordless **email-code** logi
 
 **This is for ad-hoc visual verification, not test authoring.** If you're writing a Playwright suite or debugging a failing CI run, use the `e2e-testing` skill — it owns the canonical login helper and the PrimeNG selector quirks.
 
-## The core idea (driver-agnostic)
+## Two auth flows — check which one first
+
+- **Header flow** (`Login` + `RefreshTokenWithHeaders`): tokens in localStorage → recipe below.
+- **Cookie flow** (`LoginWithCookies` + `RefreshTokenWithCookies`): the refresh token is an HttpOnly cookie — localStorage injection can't work. Symptom: bearer fetches return 200, yet every load bounces to `/login` with a 401 on `RefreshTokenWithCookies`. Log in **from inside the browser** with `credentials: 'include'` instead:
+
+```js
+// eval on the admin origin; email must have the Admin role
+const browserId = 'verify-ui';
+localStorage.setItem('browser_id', browserId); // must match the login below
+const { verificationCode } = await (await fetch(API + '/api/Security/SendLoginVerificationEmail', {
+  method: 'POST', headers: {'Content-Type':'application/json'}, credentials: 'include',
+  body: JSON.stringify({ email, browserId }) })).json();
+await fetch(API + '/api/Security/LoginWithCookies', { method: 'POST',
+  headers: {'Content-Type':'application/json'}, credentials: 'include',
+  body: JSON.stringify({ verificationCode, email, browserId }) });
+// reload — boot's RefreshTokenWithCookies now finds the cookie
+```
+
+## The core idea — header flow (driver-agnostic)
 
 In development, `SecurityService.SendLoginVerificationEmail` returns the verification code **in the response body** (when `ShouldShowVerificationCodeInNotification()` is true — i.e. `IWebHostEnvironment.IsDevelopment()` **and** SMTP is not fully configured, so `emailingService.IsConfigured()` is false). So no email inbox is needed. The flow is always:
 

package/fesm2022/spiderly.mjs

@@ -1128,7 +1128,7 @@ class SpiderlyEditorComponent extends BaseControl {
     imageHandler(quill) {
         const input = document.createElement('input');
         input.setAttribute('type', 'file');
-        input.setAttribute('accept', 'image/*');
+        input.setAttribute('accept', this.acceptedFileTypes?.join(',') ?? 'image/*');
         input.click();
         input.onchange = async () => {
             const file = input.files[0];
@@ -1140,8 +1140,12 @@ class SpiderlyEditorComponent extends BaseControl {
                     quill.insertEmbed(range.index, 'image', result.url);
                     // Quill 2's built-in Image blot recognizes width/height as native attributes,
                     // so formatText writes them directly onto the rendered <img>. Storefront uses
-                    // these to size the image up-front and prevent CLS.
-                    quill.formatText(range.index, 1, { width: result.width, height: result.height });
+                    // these to size the image up-front and prevent CLS. (0, 0) means the server
+                    // couldn't determine an intrinsic size (e.g. an SVG without width/viewBox) —
+                    // omit the attributes entirely rather than render an invisible 0×0 image.
+                    if (result.width && result.height) {
+                        quill.formatText(range.index, 1, { width: result.width, height: result.height });
+                    }
                     quill.setSelection(range.index + 1);
                 });
             }
@@ -1154,7 +1158,7 @@ class SpiderlyEditorComponent extends BaseControl {
         };
     }
     static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "19.2.13", ngImport: i0, type: SpiderlyEditorComponent, deps: [{ token: i1.TranslocoService }], target: i0.ɵɵFactoryTarget.Component }); }
-    static { this.ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "19.2.13", type: SpiderlyEditorComponent, isStandalone: true, selector: "spiderly-editor", inputs: { uploadImageMethod: "uploadImageMethod", objectId: "objectId" }, viewQueries: [{ propertyName: "editor", first: true, predicate: Editor, descendants: true }], usesInheritance: true, ngImport: i0, template: "<!-- Can't put (onBlur) in this control -->\n\n<div style=\"display: flex; flex-direction: column; gap: 0.5rem; padding: 0 1px\">\n  <div *ngIf=\"getTranslatedLabel() != '' && getTranslatedLabel() != null\">\n    <label>{{ getTranslatedLabel() }}</label>\n    <required *ngIf=\"control?.required && showRequired\"></required>\n  </div>\n\n  <!-- Disable doesn't work on this control -->\n  <p-editor\n    *ngIf=\"control\"\n    [formControl]=\"control\"\n    [readonly]=\"control.disabled\"\n    [class]=\"control.invalid && control.dirty ? 'control-error-border' : ''\"\n    [id]=\"control.label\"\n    [placeholder]=\"placeholder\"\n    (click)=\"onClick()\"\n    (onInit)=\"onEditorInit($event)\"\n    [style]=\"{ height: '320px' }\"\n  ></p-editor>\n  <small *ngIf=\"control?.errors && control?.dirty\" class=\"spiderly-error-message\">\n    {{ getValidationErrrorMessages() }}\n  </small>\n</div>\n", dependencies: [{ kind: "ngmodule", type: CommonModule }, { kind: "directive", type: i2.NgIf, selector: "[ngIf]", inputs: ["ngIf", "ngIfThen", "ngIfElse"] }, { kind: "ngmodule", type: ReactiveFormsModule }, { kind: "directive", type: i3.NgControlStatus, selector: "[formControlName],[ngModel],[formControl]" }, { kind: "directive", type: i3.FormControlDirective, selector: "[formControl]", inputs: ["formControl", "disabled", "ngModel"], outputs: ["ngModelChange"], exportAs: ["ngForm"] }, { kind: "ngmodule", type: FormsModule }, { kind: "ngmodule", type: EditorModule }, { kind: "component", type: i4$8.Editor, selector: "p-editor", inputs: ["style", "styleClass", "placeholder", "formats", "modules", "bounds", "scrollingContainer", "debug", "readonly"], outputs: ["onInit", "onTextChange", "onSelectionChange"] }, { kind: "component", type: RequiredComponent, selector: "required" }] }); }
+    static { this.ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "19.2.13", type: SpiderlyEditorComponent, isStandalone: true, selector: "spiderly-editor", inputs: { uploadImageMethod: "uploadImageMethod", objectId: "objectId", acceptedFileTypes: "acceptedFileTypes" }, viewQueries: [{ propertyName: "editor", first: true, predicate: Editor, descendants: true }], usesInheritance: true, ngImport: i0, template: "<!-- Can't put (onBlur) in this control -->\n\n<div style=\"display: flex; flex-direction: column; gap: 0.5rem; padding: 0 1px\">\n  <div *ngIf=\"getTranslatedLabel() != '' && getTranslatedLabel() != null\">\n    <label>{{ getTranslatedLabel() }}</label>\n    <required *ngIf=\"control?.required && showRequired\"></required>\n  </div>\n\n  <!-- Disable doesn't work on this control -->\n  <p-editor\n    *ngIf=\"control\"\n    [formControl]=\"control\"\n    [readonly]=\"control.disabled\"\n    [class]=\"control.invalid && control.dirty ? 'control-error-border' : ''\"\n    [id]=\"control.label\"\n    [placeholder]=\"placeholder\"\n    (click)=\"onClick()\"\n    (onInit)=\"onEditorInit($event)\"\n    [style]=\"{ height: '320px' }\"\n  ></p-editor>\n  <small *ngIf=\"control?.errors && control?.dirty\" class=\"spiderly-error-message\">\n    {{ getValidationErrrorMessages() }}\n  </small>\n</div>\n", dependencies: [{ kind: "ngmodule", type: CommonModule }, { kind: "directive", type: i2.NgIf, selector: "[ngIf]", inputs: ["ngIf", "ngIfThen", "ngIfElse"] }, { kind: "ngmodule", type: ReactiveFormsModule }, { kind: "directive", type: i3.NgControlStatus, selector: "[formControlName],[ngModel],[formControl]" }, { kind: "directive", type: i3.FormControlDirective, selector: "[formControl]", inputs: ["formControl", "disabled", "ngModel"], outputs: ["ngModelChange"], exportAs: ["ngForm"] }, { kind: "ngmodule", type: FormsModule }, { kind: "ngmodule", type: EditorModule }, { kind: "component", type: i4$8.Editor, selector: "p-editor", inputs: ["style", "styleClass", "placeholder", "formats", "modules", "bounds", "scrollingContainer", "debug", "readonly"], outputs: ["onInit", "onTextChange", "onSelectionChange"] }, { kind: "component", type: RequiredComponent, selector: "required" }] }); }
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.13", ngImport: i0, type: SpiderlyEditorComponent, decorators: [{
             type: Component,
@@ -1172,6 +1176,8 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.13", ngImpo
                 type: Input
             }], objectId: [{
                 type: Input
+            }], acceptedFileTypes: [{
+                type: Input
             }] } });
 
 /**