cabloy 5.1.239 → 5.1.241

package/.cabloy-version

@@ -1 +1 @@
-5.1.239
+5.1.241

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 5.1.241
+
+### Features
+
+- Display the user's display name.
+- Add MCP permission support.
+- Add guard-only permission checks.
+
+### Improvements
+
+- Update the OpenAPI guide.
+
+## 5.1.240
+
+### Improvements
+
+- Enhance rate limiting.
+- Update hot module replacement (HMR) handling.
+
 ## 5.1.239
 
 ### Improvements

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.239",
+  "version": "5.1.241",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "A Node.js fullstack framework",
   "keywords": [

package/repo-docs/backend/openapi-guide.md

@@ -48,6 +48,24 @@ Representative capabilities include generating JSON for:
 
 This is important because OpenAPI is treated as a first-class framework service, not as an external afterthought.
 
+## MCP mapping and normal ingress admission
+
+In Cabloy Basic, method/class `@mcp.tool()` metadata opts registered Controller Actions into MCP mapping using their existing request/response contracts. It is independent of ordinary OpenAPI publication: `@Api.exclude()` is not an MCP authorization boundary, and publishing an HTTP action does not opt it into MCP. Decorator opt-in alone does **not** expose an action on normal `/mcp`.
+
+Normal shared ingress is owned by `cabloy-mcp` and accepts recognized dev/test/prod modes through the same OAuth and business-authorization boundary. Production is not rejected solely by mode; unknown modes, not-ready, closing, disabled or invalid required authority configuration still fail closed. Dedicated protected audit, audit-delivery gating and deployment-wide fine-grained quotas are deferred for this two-read MVP, not delivered capabilities or production prerequisites. Enabled-by-default behavior is unchanged: only literal `CABLOY_MCP_ENABLED=false` disables it. Construction admission permits exactly `training-student.controller.student` actions `lookup` and `summary`, for both listing and known-name direct calls. Optional training absent means an empty catalog, without fallback. The three synthetic catalog tools and anonymous standalone entry belong only to the `mcp-test` launcher, not shared `/mcp`.
+
+OAuth scope does not grant business authority. Lookup and summary retain independent student select/view permissions, current-instance reads and minimized output; summary's six-field projection does not change its HTTP DTO. Calls retain ordinary Action guards with `innerAccess: false`.
+
+Repository-relative source pointers:
+
+- Opt-in metadata: `vona/src/suite-vendor/a-vona/modules/a-openapiutils/src/lib/decorator/mcp.ts`
+- Contract mapper: `vona/src/suite/cabloy-mcp/modules/cabloy-mcp/src/lib/controllerTools.ts`
+- Normal ingress middleware: `vona/src/suite/cabloy-mcp/modules/cabloy-mcp/src/bean/middlewareSystem.mcp.ts`
+- Ingress checks: `vona/src/suite/cabloy-mcp/modules/cabloy-mcp/src/lib/mcpTransport.ts`
+- Authenticated exchange and settlement: `vona/src/suite/cabloy-mcp/modules/cabloy-mcp/src/lib/businessTransport.ts`
+- Exact admission and discovery: `vona/src/suite/cabloy-mcp/modules/cabloy-mcp/src/lib/sharedBusinessTools.ts`
+- Application-close drain: `vona/src/suite/cabloy-mcp/modules/cabloy-mcp/src/monkey.ts`
+
 ## Validation and OpenAPI are linked
 
 A major theme is that the same validation-oriented declaration surface also drives OpenAPI metadata generation.

package/repo-docs/backend/rate-limit-guide.md

@@ -2,11 +2,56 @@
 
 ## Overview
 
-`a-ratelimit` limits matched Vona HTTP API actions across all application workers. It runs as the global `a-ratelimit:rateLimit` interceptor after Passport has resolved an authenticated or anonymous subject, and before request-body parsing, pipes, local middleware, and controller code. See [Controller AOP Guide](/backend/controller-aop-guide) for the general request-stage diagram and the distinction between a local aspect and a route override of an existing global onion.
+`a-ratelimit` provides two independent admission controls:
 
-It protects controller APIs. Put volumetric, static-file, unknown-route, and network-edge protection in the reverse proxy, WAF, or gateway.
+- The identity interceptor, `a-ratelimit:rateLimit`, limits matched Vona HTTP API actions across all application workers. It runs after Passport has resolved an authenticated or anonymous subject, and before request-body parsing, pipes, local middleware, and controller code.
+- The aggregate system middleware, `a-ratelimit:aggregate`, limits incoming HTTP requests across the application before the application/instance readiness middleware and routing, but after the HTTP executor's initial instance lookup. It is disabled by default and requires explicit configuration.
 
-## Enablement and rollout
+The identity interceptor protects controller APIs only; its route matching and instance isolation do not describe the aggregate middleware. Keep volumetric and network-edge protection in the reverse proxy, WAF, or gateway even when aggregate admission is enabled. See [Controller AOP Guide](/backend/controller-aop-guide) for the general request-stage diagram and the distinction between a local aspect and a route override of an existing global onion.
+
+The aggregate middleware documented here is a Cabloy Basic runtime addition. Cabloy Start is maintained separately and does not automatically receive this runtime change; shared documentation does not imply aggregate middleware availability in Start.
+
+## Aggregate application admission
+
+Enable the system middleware through application configuration, starting in observe mode:
+
+```ts
+config.onions.middlewareSystem['a-ratelimit:aggregate'] = {
+  enable: true,
+  rateLimit: {
+    mode: 'observe',
+    limit: 100,
+  },
+};
+```
+
+`100` is an example limit, not a measured application capacity or a recommended production value. An enabled aggregate middleware requires an explicit valid `limit` and a `mode` of either `'observe'` or `'enforce'`; there is no enabled default quota. Review observed traffic and Redis health before changing `mode` to `'enforce'`.
+
+### Coverage and ordering
+
+The aggregate middleware runs after `httpLog` and before health handling, the application/instance readiness middleware, routing, and authentication. The HTTP listener enters the executor first: it resolves the instance name and, when applicable, loads the instance record before dispatching system middleware. Aggregate admission does not protect that initial lookup or any instance registration it triggers, and requests that fail before middleware dispatch are not counted.
+
+By default, aggregate admission covers all requests that reach the system middleware chain, including API, SSR, static-file, preflight, health, and unknown-route requests. Standard system middleware `match` and `ignore` options can narrow this coverage; they match the incoming `ctx.path`, including the API prefix where present, before routing. Traffic served entirely by a proxy or CDN never reaches this counter. Other programs, background work, and later WebSocket messages are outside its coverage.
+
+Aggregate admission is independent of the identity interceptor. Both can be enabled, and a controller/action identity policy with `enable: false` does not bypass aggregate admission. There are no built-in aggregate path exemptions: unless explicitly excluded through system middleware matching, saturation can reject health probes and control requests before their handlers run. Account for this operational consequence before enforcing the quota.
+
+### Shared counter and fixed windows
+
+The aggregate counter uses the `limiter` Redis client and the application Redis prefix. It is shared across users, routes, instances, and workers rather than partitioned by identity or active instance. Multiple hosts using the same prefix and Redis share the quota; this is not physical-host discovery or an automatic per-host capacity limit. Keep custom application prefixes unique for applications or environments that require independent quotas.
+
+The window is fixed at `1000` ms and aligned to one-second boundaries. Attempts count toward the window, including requests already rejected for exceeding the limit. As with other fixed-window counters, traffic can burst around a window boundary; the limit is not a rolling-window guarantee.
+
+### Modes, responses, and logs
+
+In `observe` mode, requests over the limit log `rate_limit.would_reject` and still continue to the next middleware. Redis failures log `rate_limit.redis_error` and fail open, allowing the request to continue.
+
+In `enforce` mode, an over-limit request logs `rate_limit.rejected` and returns HTTP `429` with `Retry-After`. A Redis failure logs `rate_limit.redis_error` and returns HTTP `503` instead of allowing unbounded admission. Both responses are direct JSON bodies with the shape `{ code, message }`, even for requests expecting HTML; they do not enter the normal page/error rendering path.
+
+Aggregate admission does not add success `RateLimit-*` headers. The identity interceptor's response headers remain unchanged when a request reaches that interceptor.
+
+Aggregate logs use the same event names as the identity interceptor, with `scope: 'aggregate'`. Redis failures expose only a sanitized error class, not a raw error message. Do not include raw identities, routes, full URLs, or Redis keys in aggregate logs or metric labels.
+
+## Identity interceptor enablement and rollout
 
 The interceptor ships with `enable: false` to preserve compatibility. Enable the global interceptor through standard onion configuration and begin in observe mode:
 
@@ -36,9 +81,9 @@ config.onions.interceptor['a-ratelimit:rateLimit'] = {
 };
 ```
 
-Use instance configuration when tenants require different policy values. Each limiter key always includes the active instance, so one instance never consumes another instance’s quota.
+Use instance configuration when tenants require different identity policy values. Each identity interceptor key includes the active instance, so one instance never consumes another instance’s identity quota. The aggregate middleware instead shares one application-prefix quota across instances.
 
-## Route policies
+## Identity route policies
 
 Use `Core.rateLimit(...)` on a controller for its baseline policy, or on an action for a stricter policy, an intentional shared bucket, or an explicit exemption:
 
@@ -64,7 +109,7 @@ async requestReset() {}
 health() {}
 ```
 
-`enable`, matching, and ordering remain outer interceptor options. The nested `rateLimit` object contains the quota policy, so partial controller/action overrides inherit the remaining policy fields through normal Vona onion merging. Interceptor options use normal Vona precedence: application config, active-instance config, controller/action decorators, then controlled dynamic onion overrides used by tests. A controller/action can enable a narrower policy while the global interceptor is disabled, or set `enable: false` as a reviewed exemption after global activation. Do not put this policy in another middleware’s options: only `a-ratelimit:rateLimit` consumes the `rateLimit` object at the post-Passport interceptor stage.
+`enable`, matching, and ordering remain outer interceptor options. The nested `rateLimit` object contains the quota policy, so partial controller/action overrides inherit the remaining policy fields through normal Vona onion merging. Interceptor options use normal Vona precedence: application config, active-instance config, controller/action decorators, then controlled dynamic onion overrides used by tests. A controller/action can enable a narrower policy while the global interceptor is disabled, or set `enable: false` as a reviewed exemption after global activation. These identity policy fields belong to `a-ratelimit:rateLimit` at the post-Passport interceptor stage, not to another middleware. The aggregate system middleware has its own independent `rateLimit` configuration described above.
 
 ## Identity and Redis storage
 
@@ -72,11 +117,11 @@ The default `key: 'identity'` combines the proxy-trusted `ctx.ip` with the authe
 
 Do not parse `X-Forwarded-For` in application code. Vona resolves `ctx.ip` according to its configured proxy trust settings. The trusted reverse proxy must replace client-supplied forwarding headers before forwarding a request.
 
-The limiter always uses the dedicated `limiter` Redis client; this infrastructure choice is not a route-policy field. It registers one atomic Lua fixed-window counter command during module startup and invokes that command for each request. Redis keys contain the instance, policy, normalized route, window start, and a SHA-256 digest of the identity; raw IP addresses and subject IDs are not stored in key text.
+The identity interceptor always uses the dedicated `limiter` Redis client; this infrastructure choice is not a route-policy field. It registers one atomic Lua fixed-window counter command during module startup and invokes that command for each evaluated request. Identity Redis keys contain the instance, policy, normalized route, window start, and a SHA-256 digest of the identity; raw IP addresses and subject IDs are not stored in key text.
 
 Fixed windows provide one low-cost atomic operation per request. A limit can burst around a window boundary; choose lower limits or shorter windows for especially sensitive actions.
 
-## HTTP response contract
+## Identity HTTP response contract
 
 In enforce mode, evaluated requests expose RFC 9333 fields when `headers` is enabled:
 
@@ -90,7 +135,7 @@ If the limiter Redis operation fails during enforce mode, Cabloy returns `503`,
 
 ## Operations
 
-The primary structured events are `rate_limit.would_reject`, `rate_limit.rejected`, and `rate_limit.redis_error`. They contain only route/policy/instance and error-class information; do not add raw identities, full URLs, or Redis keys to logs or metric labels.
+The primary structured events are `rate_limit.would_reject`, `rate_limit.rejected`, and `rate_limit.redis_error`. Identity interceptor events contain only route/policy/instance and error-class information. Aggregate events carry `scope: 'aggregate'` and omit route/identity detail, with only a sanitized error class for Redis failures. Do not add raw identities, full URLs, or Redis keys to logs or metric labels.
 
 The `limiter` client may initially use the same Redis deployment as other Vona clients, but it is separately configured so production can isolate its endpoint, timeout, and capacity. Ensure Redis remains available before globally setting `enable: true` with `rateLimit.mode: 'enforce'`.
 

package/repo-e2e/specs/home-user-account.spec.ts

@@ -383,7 +383,7 @@ test(
 );
 
 test(
-  'ATP-ACCOUNT-WEB-01: signed-in Web menu refreshes after profile save and keeps drafts isolated',
+  'ATP-ACCOUNT-WEB-01: display name refreshes the Web menu without changing the login username',
   { tag: ['@account', '@web', '@flow'] },
   async ({ page, request }, testInfo) => {
     let account: RegisteredAccount | undefined;
@@ -424,14 +424,27 @@ test(
         .poll(() => avatarPreview.evaluate(image => (image as HTMLImageElement).naturalWidth))
         .toBeGreaterThan(0);
 
-      const profileName = `e2e-fixture-home-account-profile-${testInfo.workerIndex}-${crypto.randomUUID()}`;
-      await page
+      const username = page.getByRole('textbox', { name: 'User name', exact: true });
+      await expect(username).toHaveValue(account.username);
+      await expect(username).toHaveAttribute('readonly', '');
+      const displayName = page
         .getByRole('group', { name: 'Display name', exact: true })
-        .getByRole('textbox')
-        .fill(profileName);
+        .getByRole('textbox');
+      await expect(displayName).toHaveValue('');
+      const profileName = `e2e-fixture-home-account-profile-${testInfo.workerIndex}-${crypto.randomUUID()}`;
+      await displayName.fill(`  ${profileName}  `);
       const timezone = page
         .getByRole('group', { name: 'Time zone', exact: true })
         .getByRole('textbox');
+      const inputWidths = await Promise.all(
+        [username, displayName, timezone].map(input =>
+          input.evaluate(element => element.getBoundingClientRect().width),
+        ),
+      );
+      expect(inputWidths[0]).toBeGreaterThan(0);
+      for (const width of inputWidths.slice(1)) {
+        expect(width).toBeCloseTo(inputWidths[0], 0);
+      }
       const browserTimezone = await page.evaluate(
         () => Intl.DateTimeFormat().resolvedOptions().timeZone,
       );
@@ -447,9 +460,21 @@ test(
       const profileResponse = waitForApiResponse(page, 'PATCH', accountProfileApiPath);
       const refreshedPassportResponse = waitForApiResponse(page, 'GET', passportCurrentApiPath);
       await page.getByRole('button', { name: 'Save profile', exact: true }).click();
-      expect((await profileResponse).ok()).toBeTruthy();
-      account.username = profileName;
-      expect((await refreshedPassportResponse).ok()).toBeTruthy();
+      const savedProfileResponse = await profileResponse;
+      expect(savedProfileResponse.ok()).toBeTruthy();
+      expect((await savedProfileResponse.json()).data).toMatchObject({
+        name: account.username,
+        displayName: profileName,
+      });
+      expect(savedProfileResponse.request().postDataJSON()).not.toHaveProperty('name');
+      const savedPassportResponse = await refreshedPassportResponse;
+      expect(savedPassportResponse.ok()).toBeTruthy();
+      expect((await savedPassportResponse.json()).data.user).toMatchObject({
+        name: account.username,
+        displayName: profileName,
+      });
+      await expect(username).toHaveValue(account.username);
+      await expect(displayName).toHaveValue(profileName);
       await expect(page.getByText('Profile saved.', { exact: true })).toBeVisible();
       await expect
         .poll(() =>
@@ -473,6 +498,26 @@ test(
       await expect(page).toHaveURL(accountPath);
       await expect(page.getByRole('heading', { name: 'Account Settings' })).toBeVisible();
       await expect(userMenu).not.toHaveAttribute('open', '');
+      await expect(username).toHaveValue(account.username);
+      await expect(displayName).toHaveValue(profileName);
+      const originalLogin = await loginAsAccount(request, account.username, account.password);
+      expect(String(originalLogin.id)).toBe(String(account.id));
+
+      await displayName.fill('   ');
+      const clearedProfileResponse = waitForApiResponse(page, 'PATCH', accountProfileApiPath);
+      const clearedPassportResponse = waitForApiResponse(page, 'GET', passportCurrentApiPath);
+      await page.getByRole('button', { name: 'Save profile', exact: true }).click();
+      const clearedProfile = await clearedProfileResponse;
+      expect(clearedProfile.ok()).toBeTruthy();
+      expect(clearedProfile.request().postDataJSON()).toMatchObject({ displayName: null });
+      const clearedProfileBody = (await clearedProfile.json()).data;
+      expect(clearedProfileBody.name).toBe(account.username);
+      expect(clearedProfileBody.displayName).toBeFalsy();
+      expect((await clearedPassportResponse).ok()).toBeTruthy();
+      await expect(displayName).toHaveValue('');
+      await expect(username).toHaveValue(account.username);
+      await expect(userMenu.locator('summary')).toContainText(account.username);
+      await expect(userMenu.locator('summary')).not.toContainText(profileName);
       expect(pageErrors).toEqual([]);
       expect(consoleErrors).toEqual([]);
     } finally {

package/vona/packages-vona/vona/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona",
-  "version": "5.1.118",
+  "version": "5.1.120",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "Vona is an intuitive, elegant and powerful Node.js framework for rapidly developing enterprise applications of any size",
   "keywords": [

package/vona/pnpm-lock.yaml

@@ -995,11 +995,11 @@ importers:
         specifier: npm:@cabloy/zod@4.3.8
         version: '@cabloy/zod@4.3.8'
       zova:
-        specifier: ^5.1.176
-        version: 5.1.176(debug@4.4.3(supports-color@7.2.0))(supports-color@7.2.0)(typescript@5.9.3)(vue@3.5.43(typescript@5.9.3))
+        specifier: ^5.1.177
+        version: 5.1.177(debug@4.4.3(supports-color@7.2.0))(supports-color@7.2.0)(typescript@5.9.3)(vue@3.5.43(typescript@5.9.3))
       zova-jsx:
-        specifier: ^1.1.94
-        version: 1.1.94(typescript@5.9.3)
+        specifier: ^1.1.95
+        version: 1.1.95(typescript@5.9.3)
       zova-module-a-api:
         specifier: ^5.1.23
         version: 5.1.23
@@ -1061,8 +1061,8 @@ importers:
         specifier: ^5.1.36
         version: 5.1.36
       zova-module-a-ssr:
-        specifier: ^5.1.41
-        version: 5.1.41
+        specifier: ^5.1.42
+        version: 5.1.42
       zova-module-a-ssrhmr:
         specifier: ^5.1.24
         version: 5.1.24
@@ -1079,8 +1079,8 @@ importers:
         specifier: ^5.1.39
         version: 5.1.39
       zova-module-a-zova:
-        specifier: ^5.1.113
-        version: 5.1.113(typescript@5.9.3)(vue@3.5.43(typescript@5.9.3))
+        specifier: ^5.1.114
+        version: 5.1.114(typescript@5.9.3)(vue@3.5.43(typescript@5.9.3))
       zova-module-pay-mock:
         specifier: ^5.0.6
         version: 5.0.6
@@ -1124,11 +1124,11 @@ importers:
         specifier: npm:@cabloy/zod@4.3.8
         version: '@cabloy/zod@4.3.8'
       zova:
-        specifier: ^5.1.176
-        version: 5.1.176(debug@4.4.3(supports-color@7.2.0))(supports-color@7.2.0)(typescript@5.9.3)(vue@3.5.43(typescript@5.9.3))
+        specifier: ^5.1.177
+        version: 5.1.177(debug@4.4.3(supports-color@7.2.0))(supports-color@7.2.0)(typescript@5.9.3)(vue@3.5.43(typescript@5.9.3))
       zova-jsx:
-        specifier: ^1.1.94
-        version: 1.1.94(typescript@5.9.3)
+        specifier: ^1.1.95
+        version: 1.1.95(typescript@5.9.3)
       zova-module-a-api:
         specifier: ^5.1.23
         version: 5.1.23
@@ -1190,8 +1190,8 @@ importers:
         specifier: ^5.1.36
         version: 5.1.36
       zova-module-a-ssr:
-        specifier: ^5.1.41
-        version: 5.1.41
+        specifier: ^5.1.42
+        version: 5.1.42
       zova-module-a-ssrhmr:
         specifier: ^5.1.24
         version: 5.1.24
@@ -1208,8 +1208,8 @@ importers:
         specifier: ^5.1.39
         version: 5.1.39
       zova-module-a-zova:
-        specifier: ^5.1.113
-        version: 5.1.113(typescript@5.9.3)(vue@3.5.43(typescript@5.9.3))
+        specifier: ^5.1.114
+        version: 5.1.114(typescript@5.9.3)(vue@3.5.43(typescript@5.9.3))
       zova-module-pay-mock:
         specifier: ^5.0.6
         version: 5.0.6
@@ -9412,15 +9412,9 @@ packages:
     resolution: {integrity: sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q==}
     engines: {node: '>=10'}
 
-  zova-core@5.1.94:
-    resolution: {integrity: sha512-puo3pqa4/ngwZj//Md457XMloZ4FRaoJlmwf+zyPyxKL7GoV81BaJeUPi9szzY8aM9EkoWXBhSVA0cp6mTXBhw==}
-
   zova-core@5.1.95:
     resolution: {integrity: sha512-nvBb3zVdJEQ9SWi+cl5j2PLs/T0FRRIULfHqU3SBFUn3jFSZFizniRlak+qoSq3mzj+LGD61BfnFJQb2JJ8+Zg==}
 
-  zova-jsx@1.1.94:
-    resolution: {integrity: sha512-4QGgNE5J32PXYCgHBt8JBrTRp8CXADgZzIBUsovQmKfIwtMY6DK5+zPQeWBVqHoV5vK95RKhRPwdAKFGOLupeg==}
-
   zova-jsx@1.1.95:
     resolution: {integrity: sha512-gzmR01Qt4oBrMCejH4W0fqfFx62L+XQOfOROs6mBVdFYGmbyXzy/lDXtTH4v4WjlrmVbuoAyZE/BrYmNxn2swA==}
 
@@ -9484,9 +9478,6 @@ packages:
   zova-module-a-routertabs@5.1.36:
     resolution: {integrity: sha512-QYkeK7ql0B2AdFcCj9a+oIyqZi7oW/Ay/YHMFSseRgoRU/dTQnK79/v/DWB8+JluxY0tWMakLDcSq7bIolRdgg==}
 
-  zova-module-a-ssr@5.1.41:
-    resolution: {integrity: sha512-2p19mMzc9MjvYDdEbV6qjOngxuM7vdzwA1+Z4+/81pOfptU7nBobqDaDUNZxblHEoiIHrDM8NCeghPBO6Fz2sg==}
-
   zova-module-a-ssr@5.1.42:
     resolution: {integrity: sha512-XaZcUHwDxwyQi4VNLK6CxkdG4lV5aUNgPNkiLjN3LWh9l2yS0u8CQqGV8+gEKcpOOj7XhZIubu4gb4GUNNQoGw==}
 
@@ -9505,9 +9496,6 @@ packages:
   zova-module-a-zod@5.1.39:
     resolution: {integrity: sha512-nyVgDGt7Xly/8ccGau/ZRck3PJfo+9WFMR4EudXo2YBFMahNeXUegTyUPeSV6DfJDUjCqpy2V060PipBVJ5QzQ==}
 
-  zova-module-a-zova@5.1.113:
-    resolution: {integrity: sha512-PuasOjYgRz8F94oVPSjQepwVxL+LySauwJQKNzly+yD7YCbQJcHy6tw7IejwcaSTjlBe3M1Iy6IWX7IwrOrfyw==}
-
   zova-module-a-zova@5.1.114:
     resolution: {integrity: sha512-H16jQ2YRw3Q9KSO7RDKMl+QRFZSZ7J/AkUUD71BTQA1oDLY+zBLuKTABwicEgS3S44R4qJC79rR/yuTXLlZnkw==}
 
@@ -9523,15 +9511,9 @@ packages:
   zova-module-rest-resource@5.1.57:
     resolution: {integrity: sha512-xpx42J+ZCx3KGzFZPQBHfUUDxgYTPlQGrUTrN0/SCY8PD/qYu77kqQ29+B5B9WcUeSnSAzUtbZx0UzzFia1slQ==}
 
-  zova-suite-a-zova@5.1.175:
-    resolution: {integrity: sha512-cjN97iaDZ3WhvOtu27YnqfZpEnnKptLGqqpllIhAtOFaTXtuMGiGVTmH7Q1tc/k9OPEHzvvCThsYKRxzYbR5DQ==}
-
   zova-suite-a-zova@5.1.176:
     resolution: {integrity: sha512-w7JQ0cutO3zaZosxfsSLn9/mcY5deftZWTGkiPJTTG6I6eGGZlFJRDCQpu+dBd8eYI66xe4kstdH3KGhLSt74A==}
 
-  zova@5.1.176:
-    resolution: {integrity: sha512-7E/Kc9QkuB6ckDX2ual9DFmiVrcPy/umDVlC+QlRFy5A30L8D5/WNKzWxmBubXYsXWmsAd/VZQUQPwditMmNkA==}
-
   zova@5.1.177:
     resolution: {integrity: sha512-35jZVs08Qn4cybwNqu1/PE3qz1J7Vi64y7AgTD98rVv5uOnDPkuwIIIVgMYZllV/C3kCsWPBLoC3tz/UG4SEcA==}
 
@@ -15880,37 +15862,6 @@ snapshots:
 
   yocto-queue@0.1.0: {}
 
-  zova-core@5.1.94(typescript@5.9.3):
-    dependencies:
-      '@cabloy/compose': link:packages-utils/compose
-      '@cabloy/extend': link:packages-utils/extend
-      '@cabloy/json5': link:packages-utils/json5
-      '@cabloy/localeutil': link:packages-utils/localeutil
-      '@cabloy/logger': 1.1.25
-      '@cabloy/module-info': 2.0.3
-      '@cabloy/utils': link:packages-utils/utils
-      '@cabloy/vue-compiler-sfc': 3.5.14
-      '@cabloy/vue-reactivity': 3.5.16
-      '@cabloy/vue-router': 4.4.18(vue@3.5.43(typescript@5.9.3))
-      '@cabloy/vue-runtime-core': 3.5.57
-      '@cabloy/vue-runtime-dom': 3.5.13
-      '@cabloy/vue-server-renderer': 3.5.18(vue@3.5.43(typescript@5.9.3))
-      '@cabloy/word-utils': 2.1.14
-      '@cabloy/zod-errors-custom': link:packages-utils/zod-errors-custom
-      '@cabloy/zod-openapi': link:packages-utils/zod-openapi
-      '@cabloy/zod-query': link:packages-utils/zod-query
-      '@types/js-cookie': 3.0.6
-      '@types/ms': 2.1.0
-      '@vue/shared': 3.5.36
-      deep-equal: 2.2.3
-      ms: 2.1.3
-      reflect-metadata: 0.2.2
-      vue: 3.5.43(typescript@5.9.3)
-      vue-plugin-render-freeze: 2.0.4(vue@3.5.43(typescript@5.9.3))
-      zod: '@cabloy/zod@4.3.8'
-    transitivePeerDependencies:
-      - typescript
-
   zova-core@5.1.95(patch_hash=44197c3f359a73a1a5bb3dc0a8a97e705a55b30f9a434717aa24d75a96f2c6b6)(typescript@5.9.3):
     dependencies:
       '@cabloy/compose': link:packages-utils/compose
@@ -15942,17 +15893,6 @@ snapshots:
     transitivePeerDependencies:
       - typescript
 
-  zova-jsx@1.1.94(typescript@5.9.3):
-    dependencies:
-      '@cabloy/compose': link:packages-utils/compose
-      '@cabloy/utils': link:packages-utils/utils
-      '@cabloy/word-utils': 2.1.14
-      typestyle: 2.4.0
-      vue: 3.5.43(typescript@5.9.3)
-      zova-core: 5.1.94(typescript@5.9.3)
-    transitivePeerDependencies:
-      - typescript
-
   zova-jsx@1.1.95(typescript@5.9.3):
     dependencies:
       '@cabloy/compose': link:packages-utils/compose
@@ -16033,11 +15973,6 @@ snapshots:
 
   zova-module-a-routertabs@5.1.36: {}
 
-  zova-module-a-ssr@5.1.41:
-    dependencies:
-      devalue: 5.9.4
-      ms: 2.1.3
-
   zova-module-a-ssr@5.1.42:
     dependencies:
       devalue: 5.9.4
@@ -16071,22 +16006,6 @@ snapshots:
       '@cabloy/zod-query': link:packages-utils/zod-query
       zod: '@cabloy/zod@4.3.8'
 
-  zova-module-a-zova@5.1.113(typescript@5.9.3)(vue@3.5.43(typescript@5.9.3)):
-    dependencies:
-      '@cabloy/compose': link:packages-utils/compose
-      '@cabloy/deps': link:packages-utils/deps
-      '@cabloy/json5': link:packages-utils/json5
-      '@cabloy/module-info': 2.0.3
-      '@cabloy/utils': link:packages-utils/utils
-      '@cabloy/vue-router': 4.4.18(vue@3.5.43(typescript@5.9.3))
-      '@cabloy/word-utils': 2.1.14
-      defu: 6.1.7
-      luxon: 3.7.2
-      zova-jsx: 1.1.94(typescript@5.9.3)
-    transitivePeerDependencies:
-      - typescript
-      - vue
-
   zova-module-a-zova@5.1.114(typescript@5.9.3)(vue@3.5.43(typescript@5.9.3)):
     dependencies:
       '@cabloy/compose': link:packages-utils/compose
@@ -16111,39 +16030,6 @@ snapshots:
 
   zova-module-rest-resource@5.1.57: {}
 
-  zova-suite-a-zova@5.1.175(debug@4.4.3(supports-color@7.2.0))(supports-color@7.2.0)(typescript@5.9.3)(vue@3.5.43(typescript@5.9.3)):
-    dependencies:
-      zova-module-a-api: 5.1.23
-      zova-module-a-app: 5.1.27
-      zova-module-a-bean: 5.1.37
-      zova-module-a-behavior: 5.1.28
-      zova-module-a-behaviors: 5.1.23
-      zova-module-a-command: 5.1.36
-      zova-module-a-fetch: 5.1.26(debug@4.4.3(supports-color@7.2.0))(supports-color@7.2.0)
-      zova-module-a-form: 5.1.55(vue@3.5.43(typescript@5.9.3))
-      zova-module-a-icon: 5.1.28
-      zova-module-a-interceptor: 5.1.32
-      zova-module-a-logger: 5.1.29
-      zova-module-a-meta: 5.1.23
-      zova-module-a-model: 5.1.39(vue@3.5.43(typescript@5.9.3))
-      zova-module-a-openapi: 5.1.59
-      zova-module-a-router: 5.1.43
-      zova-module-a-routerstack: 5.1.30
-      zova-module-a-routertabs: 5.1.36
-      zova-module-a-ssr: 5.1.41
-      zova-module-a-ssrhmr: 5.1.24
-      zova-module-a-ssrserver: 5.1.27
-      zova-module-a-style: 5.1.36
-      zova-module-a-table: 5.1.45(vue@3.5.43(typescript@5.9.3))
-      zova-module-a-zod: 5.1.39
-      zova-module-a-zova: 5.1.113(typescript@5.9.3)(vue@3.5.43(typescript@5.9.3))
-    transitivePeerDependencies:
-      - '@vue/composition-api'
-      - debug
-      - supports-color
-      - typescript
-      - vue
-
   zova-suite-a-zova@5.1.176(debug@4.4.3(supports-color@7.2.0))(supports-color@7.2.0)(typescript@5.9.3)(vue@3.5.43(typescript@5.9.3)):
     dependencies:
       zova-module-a-api: 5.1.23
@@ -16177,17 +16063,6 @@ snapshots:
       - typescript
       - vue
 
-  zova@5.1.176(debug@4.4.3(supports-color@7.2.0))(supports-color@7.2.0)(typescript@5.9.3)(vue@3.5.43(typescript@5.9.3)):
-    dependencies:
-      zova-core: 5.1.94(typescript@5.9.3)
-      zova-suite-a-zova: 5.1.175(debug@4.4.3(supports-color@7.2.0))(supports-color@7.2.0)(typescript@5.9.3)(vue@3.5.43(typescript@5.9.3))
-    transitivePeerDependencies:
-      - '@vue/composition-api'
-      - debug
-      - supports-color
-      - typescript
-      - vue
-
   zova@5.1.177(debug@4.4.3(supports-color@7.2.0))(supports-color@7.2.0)(typescript@5.9.3)(vue@3.5.43(typescript@5.9.3)):
     dependencies:
       zova-core: 5.1.95(patch_hash=44197c3f359a73a1a5bb3dc0a8a97e705a55b30f9a434717aa24d75a96f2c6b6)(typescript@5.9.3)

package/vona/src/suite/a-commerce/modules/commerce-siteadmin/src/dto/operatorContext.ts

@@ -1,6 +1,6 @@
 import type { IDecoratorDtoOptions } from 'vona-module-a-web';
 
-import { Api } from 'vona-module-a-openapiutils';
+import { Api, v } from 'vona-module-a-openapiutils';
 import { Dto } from 'vona-module-a-web';
 
 export interface IDtoOptionsOperatorContext extends IDecoratorDtoOptions {}
@@ -18,4 +18,7 @@ export class DtoOperatorContext {
 
   @Api.field()
   userName: string;
+
+  @Api.field(v.optional())
+  displayName?: string;
 }

package/vona/src/suite/a-commerce/modules/commerce-siteadmin/src/service/operator.ts

@@ -13,6 +13,7 @@ export class ServiceOperator extends BeanBase {
       instanceName: instanceName ?? '',
       userId: user.id.toString(),
       userName: user.name,
+      displayName: user.displayName,
     };
   }
 }

package/vona/src/suite/a-commerce/modules/commerce-siteadmin/test/operatorAccess.test.ts

@@ -47,6 +47,7 @@ describe('operatorAccess.test.ts', () => {
         assert.equal(result.instanceName, app.ctx.instanceName);
         assert.equal(result.userId, app.bean.passport.current!.user!.id.toString());
         assert.equal(result.userName, app.bean.passport.current!.user!.name);
+        assert.equal(result.displayName, app.bean.passport.current!.user!.displayName);
       } finally {
         await app.bean.passport.signout();
       }

package/vona/src/suite/a-home/modules/home-user/src/bean/meta.version.ts

@@ -32,6 +32,7 @@ export class MetaVersion extends BeanBase implements IMetaVersionUpdate, IMetaVe
         table.comment(entityUser.$comment.$table);
         table.basicFields();
         table.string(entityUser.name, 255).comment(entityUser.$comment.name);
+        table.string(entityUser.displayName, 100).comment(entityUser.$comment.displayName);
         table.string(entityUser.avatar, 255).comment(entityUser.$comment.avatar);
         table.string(entityUser.email, 255).comment(entityUser.$comment.email);
         table.string(entityUser.mobile, 255).comment(entityUser.$comment.mobile);

package/vona/src/suite/a-home/modules/home-user/src/controller/passport.ts

@@ -157,6 +157,7 @@ export class ControllerPassport extends BeanBase {
       user: {
         id: user.id,
         name: user.name,
+        displayName: user.displayName,
         avatar: user.avatar,
         email: user.email,
         mobile: user.mobile,

package/vona/src/suite/a-home/modules/home-user/src/dto/accountCurrent.ts

@@ -11,6 +11,9 @@ export class DtoAccountCurrent {
   @Api.field()
   name: string;
 
+  @Api.field(v.optional())
+  displayName?: string;
+
   @Api.field(v.optional())
   avatar?: string;
 

package/vona/src/suite/a-home/modules/home-user/src/dto/accountProfileUpdate.ts

@@ -29,8 +29,15 @@ const avatarSchema = avatar.openapi({
 
 @Dto<IDtoOptionsAccountProfileUpdate>()
 export class DtoAccountProfileUpdate {
-  @Api.field(v.title($locale('AccountDisplayName')), v.min(1), v.max(100), v.trim())
-  name: string;
+  @Api.field(
+    v.title($locale('AccountDisplayName')),
+    z.preprocess(
+      // Preserve an explicit clear before optional-string coercion treats '' as omitted.
+      value => (value === '' ? null : value),
+      z.string().trim().max(100).nullable().optional(),
+    ),
+  )
+  displayName?: string | null;
 
   @Api.field(v.title($locale('AccountAvatar')), v.optional(), v.nullable(), avatarSchema)
   avatar?: string | null;

package/vona/src/suite/a-home/modules/home-user/src/dto/passportUser.ts

@@ -17,6 +17,9 @@ export class DtoPassportUser {
   @Api.field()
   name: string;
 
+  @Api.field(v.optional())
+  displayName?: string;
+
   @Api.field(v.optional())
   avatar?: string;
 

package/vona/src/suite/a-home/modules/home-user/src/entity/user.ts

@@ -15,6 +15,9 @@ export class EntityUser extends EntityBase implements IUser {
   @Api.field(v.title($locale('UserName')))
   name: string;
 
+  @Api.field(v.title($locale('AccountDisplayName')), z.string().trim().max(100).optional())
+  displayName?: string;
+
   @Api.field(v.title($locale('UserAvatar')), v.optional())
   avatar?: string;