cabloy 5.1.106 → 5.1.108

package/.cabloy-version

@@ -1 +1 @@
-5.1.106
+5.1.108

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 5.1.108
+
+### Features
+
+- Improve Docker domain deployment support.
+
+### Improvements
+
+- Clarify shared deployment guidance.
+
+## 5.1.107
+
+### Features
+
+- Localize persisted home roles.
+- Define response contracts for resource mutations, including null responses.
+- Secure generated CRUD actions.
+
+### Improvements
+
+- Clarify built-in role configuration.
+
 ## 5.1.106
 
 ### Improvements

package/cabloy-docs/.vitepress/config.mjs

@@ -41,6 +41,12 @@ const fullstackGroups = [
       { text: 'Suites and Modules', link: '/fullstack/suites-and-modules' },
     ],
   },
+  {
+    text: 'Fullstack / Deployment',
+    items: [
+      { text: 'Docker + Cloudflare Deployment', link: '/fullstack/deploy-cloudflare-docker' },
+    ],
+  },
   {
     text: 'Fullstack / Tutorials',
     items: [

package/cabloy-docs/backend/backend-resource-module-contract-chain.md

@@ -143,6 +143,7 @@ Representative source facts from this file:
 - the class is decorated with `@Controller<IControllerOptionsStudent>('student')`
 - the class is also decorated with `@Resource()`
 - CRUD actions are declared with `@Web.post()`, `@Web.get()`, `@Web.get(':id')`, `@Web.patch(':id')`, and `@Web.delete(':id')`
+- the standard CRUD actions and the `summary` / `deleteForce` management actions explicitly use `@Passport.systemAdmin()`
 - request shapes use `@Arg.body(...)`, `@Arg.param(...)`, and `@Arg.filter(...)`
 - actions delegate to `this.scope.service.student`
 

package/cabloy-docs/backend/controller-aop-guide.md

@@ -99,6 +99,18 @@ Typical jobs include:
 
 These shorthands still map back to the generic aspect model.
 
+### Passport inheritance and action policy
+
+The global Passport guard is the baseline for controller actions: without a local Passport decorator, an action requires an authenticated and activated user. It is not public.
+
+Use a local Passport or domain guard when an action needs a policy beyond that baseline:
+
+- use `@Passport.public()` only when anonymous access is intentional
+- use `@Passport.systemAdmin()`, `@Passport.roleName(...)`, or a domain-specific guard when access needs additional restriction
+- leave an action without a local Passport guard when authenticated-and-activated access is intentionally sufficient
+
+The CRUD generator applies `@Passport.systemAdmin()` to each generated CRUD action rather than to the controller class. This keeps the administrative default explicit while allowing a future custom action to deliberately inherit the baseline or define its own policy.
+
 For the underlying auth, passport, and user-access model, see [Auth Guide](/backend/auth-guide) and [User Access Guide](/backend/user-access-guide).
 
 ## Interceptor

package/cabloy-docs/backend/controller-guide.md

@@ -148,11 +148,11 @@ Representative pattern:
 
 ```typescript
 @Web.patch('updateUser/:id')
-updateUser(
+async updateUser(
   @Arg.param('id') id: TableIdentity,
   @Arg.body(v.object(DtoUserUpdate)) user: DtoUserUpdate,
-) {
-  return this.scope.model.user.update(user, { where: { id } });
+): Promise<void> {
+  await this.scope.service.user.update(id, user);
 }
 ```
 
@@ -208,6 +208,48 @@ A practical rule is:
 - use return-type inference when the contract is obvious and simple
 - use explicit `@Api.body(...)` when the response shape needs more control or the inference boundary becomes unclear
 
+## Resource mutation response contract
+
+Standard resource `update` and `delete` actions are command-style actions. Their public contract is successful completion, not an implicit persistence-model payload.
+
+Representative pattern:
+
+```typescript
+import { z } from 'zod';
+
+@Web.patch(':id')
+@Api.body(z.null())
+@Passport.systemAdmin()
+async update(
+  @Arg.param('id', v.tableIdentity()) id: TableIdentity,
+  @Arg.body() student: DtoStudentUpdate,
+): Promise<void> {
+  await this.scope.service.student.update(id, student);
+}
+```
+
+Use `await` without `return` at the controller boundary. A service or model may still return mutation data for internal orchestration, but that data is not automatically a stable public representation of the resource.
+
+`Promise<void>` expresses the controller's command semantics, while `@Api.body(z.null())` explicitly supplies the response schema that runtime reflection cannot recover from `Promise<void>`. It makes the existing no-payload response visible to emitted OpenAPI and generated SDK consumers.
+
+For a standard JSON action, Vona maps this no-result controller completion to its normal HTTP `200` success wrapper:
+
+```typescript
+{
+  code: 0,
+  message: 'success',
+  data: null,
+}
+```
+
+This is Vona's default resource-mutation convention. It does not use HTTP `204 No Content`, so consumers can keep one uniform success-envelope protocol.
+
+### When a mutation should return data
+
+Return data only when it is an intentional consumer-facing contract, such as an updated response DTO, a version token, or a job handle. Declare that shape explicitly with `@Api.body(...)`; add `@Core.serializer()` when the response depends on serializer transforms, exclusions, getters, or replacements. Do not forward raw ORM or service mutation results merely because the delegated method returns a value.
+
+`create` and read actions commonly expose an identity or DTO and therefore use their own explicit response contracts. For generated resource defaults, see [CRUD Workflow](/backend/crud-workflow#generated-mutation-response-default). For action-level verification, see [Unit Testing](/backend/unit-testing#testing-controllers-through-actions). When a declared response shape changes, follow the [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk) contract loop.
+
 ## Response wrapper behavior
 
 By default, Vona wraps the response body in a standard wrapper object.

package/cabloy-docs/backend/crud-workflow.md

@@ -43,6 +43,20 @@ The generator creates a connected set of files, typically including:
 
 This is exactly why this generator should be the default starting point. It gives a consistent starting shape across the backend thread.
 
+### Generated authorization default
+
+The standard generated CRUD actions (`create`, `select`, `view`, `update`, and `delete`) each use `@Passport.systemAdmin()`. This is an explicit administrative whitelist for the generated Admin resource API, matching the generated SSR menu's `systemAdmin` visibility policy.
+
+The guard is attached to individual actions rather than the controller class. When you add a custom action later, no local Passport guard intentionally means the global authenticated-and-activated baseline applies; it does not mean the action is public. Use `@Passport.public()` to intentionally allow anonymous access, or add a role/domain guard when an action needs stronger restriction.
+
+SSR menu roles control navigation disclosure only. They never authorize a controller action, API, or resource; keep the action guard as the server-side authorization boundary. See [Controller AOP Guide](/backend/controller-aop-guide) and [Menu Guide](/backend/menu-guide).
+
+### Generated mutation response default
+
+Generated resource `update` and `delete` actions are command-style actions. Their controllers use `Promise<void>`, await the service call without forwarding its result, and declare `@Api.body(z.null())` so OpenAPI and generated SDKs describe the normal HTTP `200` success wrapper accurately as `data: null`.
+
+This controller-facing default does not require the service or model mutation method to return `void`. Those lower layers may retain mutation data for internal orchestration. See [Controller Guide](/backend/controller-guide#resource-mutation-response-contract) when a mutation deliberately needs a consumer-facing response payload.
+
 A practical generated-output checklist usually includes:
 
 - controller

package/cabloy-docs/backend/multi-instance-and-instance-resolution.md

@@ -84,6 +84,24 @@ A practical fallback rule is:
 
 - subdomain-based instance resolution only becomes relevant if custom getter, query-field, and header-field resolution did not already determine the instance name
 
+## Subdomain mapping and the default instance
+
+`SERVER_SUBDOMAINOFFSET` controls how many labels at the right side of a hostname are treated as the base domain. Its default value is `2`, which fits a two-label base domain such as `cabloy.test` or `example.com`.
+
+With that default, Vona derives the instance name from the remaining labels:
+
+| Hostname              | Derived instance name |
+| --------------------- | --------------------- |
+| `cabloy.test`         | `''`                  |
+| `acme.cabloy.test`    | `acme`                |
+| `eu.acme.cabloy.test` | `acme.eu`             |
+
+The last example is intentionally `acme.eu`: Koa reverses the remaining hostname labels before Vona joins `ctx.subdomains` with `.`.
+
+The empty name `''` is the configured default instance. It is not an implicit fallback for every hostname: it can be disabled or removed. Each non-empty subdomain-derived name, including a deeper name such as `acme.eu`, must refer to an explicitly configured and enabled instance. Requests for an unknown, disabled, or deleted instance do not fall back to the default instance.
+
+If the public base domain uses a different label shape, set an explicit `SERVER_SUBDOMAINOFFSET` override that matches that domain before relying on subdomain instance resolution.
+
 ## Instance edge cases to remember
 
 A few current-runtime edge cases are worth remembering:

package/cabloy-docs/backend/runtime-and-flavors.md

@@ -52,7 +52,6 @@ cd vona && npm run build
 cd vona && npm run build:docker
 cd vona && npm run start
 cd vona && npm run start:one
-cd vona && npm run start:docker
 ```
 
 In the current repo, those scripts map naturally to:
@@ -83,9 +82,10 @@ cd vona && npm run play
 cd vona && npm run build
 cd vona && npm run build:docker
 cd vona && npm run start
-cd vona && npm run start:docker
 ```
 
+`build:docker` produces Docker-oriented output. Run that output through the Docker Compose workflow rather than a direct Vona `start:docker` command.
+
 These scripts show that the same `prod` mode can still branch into different output/runtime shapes through flavor.
 
 ## What the CLI injects automatically

package/cabloy-docs/backend/scripts.md

@@ -52,14 +52,15 @@ From the root repository:
 npm run start
 ```
 
-Vona also supports single-process and docker-oriented start modes inside its own package:
+Vona also supports its normal and single-process start modes inside its own package:
 
 ```bash
 cd vona && npm run start
 cd vona && npm run start:one
-cd vona && npm run start:docker
 ```
 
+For Docker output, use the Docker Compose workflow after `npm run build:docker`; Docker does not use a direct Vona start command.
+
 ## Test and typecheck
 
 From the root repository:

package/cabloy-docs/backend/unit-testing.md

@@ -121,13 +121,19 @@ A practical rule is:
 A representative contract-verification pattern is:
 
 ```typescript
-await app.bean.executor.performAction('patch', '/test/rest/product/:id', {
+const updateRes = await app.bean.executor.performAction('patch', '/test/rest/product/:id', {
   params: { id: productId },
   body: dataUpdate,
 });
+assert.equal(updateRes, null);
+
+const deleteRes = await app.bean.executor.performAction('delete', '/test/rest/product/:id', {
+  params: { id: productId },
+});
+assert.equal(deleteRes, null);
 ```
 
-This is a good default because the same test can exercise params, body, route wiring, validation, and response behavior together.
+For standard resource command mutations, these assertions verify the controller-facing no-payload runtime contract. Follow them with a query/read-back assertion to verify the persisted update or deletion. When the API is generated for frontend consumers, add a focused OpenAPI structural assertion that its wrapped response schema declares `data: null`; this verifies SDK-contract fidelity separately from responder behavior. The same test then exercises params, body, route wiring, validation, response behavior, and persistence effects together.
 
 ## Authentication simulation
 

package/cabloy-docs/frontend/ssr-env.md

@@ -17,9 +17,29 @@ Representative variables include:
 - `SSR_BODYREADYOBSERVER`
 - `SSR_API_BASE_URL`
 - `SSR_PROD_PORT`
+- `SSR_TRANSFERCACHE`
+- `SSR_TRANSFERCACHE_EXPIRES`
 
 These affect areas such as cookie-driven SSR behavior, theme defaults, body-load observation, server-side API targeting, and SSR production port behavior.
 
+## SSR response cache control
+
+`SSR_TRANSFERCACHE` and `SSR_TRANSFERCACHE_EXPIRES` control the `Cache-Control` response header that Zova adds after an SSR page is rendered.
+
+- `SSR_TRANSFERCACHE=false` disables this header path.
+- Any other value enables it in the current configuration normalization.
+- `SSR_TRANSFERCACHE_EXPIRES=0` emits `Cache-Control: no-cache, no-store, must-revalidate`.
+- A positive number of seconds or an `ms`-style duration such as `10m` emits `Cache-Control: public, max-age=<seconds>`.
+
+Cabloy Basic uses different flavor defaults:
+
+| Flavor | Settings                                                  | SSR response header                   |
+| ------ | --------------------------------------------------------- | ------------------------------------- |
+| Web    | `SSR_TRANSFERCACHE=true`, `SSR_TRANSFERCACHE_EXPIRES=10m` | `public, max-age=600`                 |
+| Admin  | `SSR_TRANSFERCACHE=true`, `SSR_TRANSFERCACHE_EXPIRES=0`   | `no-cache, no-store, must-revalidate` |
+
+A route can override the flavor default through its SSR route metadata. For Cloudflare cache-rule alignment that preserves these origin headers, see [Docker + Cloudflare Deployment](/fullstack/deploy-cloudflare-docker).
+
 ## Theme implications of `SSR_COOKIE`
 
 `SSR_COOKIE` is not only a storage choice. It also changes what SSR can guarantee about theme-sensitive output.

package/cabloy-docs/fullstack/deploy-cloudflare-docker.md

@@ -0,0 +1,136 @@
+# Docker + Cloudflare Deployment
+
+<Badge type="tip" text="Common" />
+
+This guide deploys Cabloy Basic or Cabloy Start in two stages: first run the fullstack application on a cloud server with Docker Compose, then put Cloudflare orange-cloud proxying in front of that origin. It covers the Vona-integrated Zova Web and Admin SSR runtime shared by both editions.
+
+Run all commands from the repository for the edition you are using. This guide documents the shared deployment contract; verify edition-specific flavor names, SSR site baselines, project assets, and repository details in the active edition source.
+
+Cloudflare Pages and Cloudflare Workers are not supported deployment targets in this guide.
+
+## Deployment model
+
+```text
+Browser
+  -> Cloudflare orange cloud
+  -> origin Nginx in Docker Compose
+  -> Vona app with Web/Admin SSR
+  -> PostgreSQL and Redis
+```
+
+The Docker Compose origin is the application deployment. Cloudflare provides DNS, edge TLS, proxying, and response caching in front of that origin.
+
+## Stage 1: deploy the Docker origin
+
+On the cloud server, clone and initialize the repository for your edition, then build and start its Docker flavor:
+
+```bash
+npm run init
+npm run build:docker
+cd vona/docker-compose
+sudo COMPOSE_BAKE=true docker-compose build
+sudo docker-compose up -d
+```
+
+The Compose stack contains the application, Nginx, PostgreSQL, and Redis. Treat database passwords, persistent volumes, backups, firewall rules, operating-system updates, and server hardening as production operator responsibilities.
+
+In the repository for the edition you are using, `vona/docker-compose/` is the generated and ignored deployment directory, while `vona/docker-compose-original/` is the tracked source template. Initialization copies the template only when the generated directory does not already exist, so upgrading the repository does not automatically update an existing generated Nginx configuration. Reconcile or regenerate that local deployment configuration deliberately, and verify the current template in your edition repository.
+
+## Local preflight with `cabloy.test`
+
+Before using a public domain, test the same hostname model locally. Use the reserved test domain `cabloy.test`, not a public domain such as `test.com`.
+
+Map every hostname that you want to test in the local hosts file, or use local DNS. For example:
+
+```text
+127.0.0.1 cabloy.test acme.cabloy.test eu.acme.cabloy.test
+```
+
+`SERVER_SUBDOMAINOFFSET` defaults to `2`. It treats the rightmost two labels as the base domain:
+
+| Hostname              | Derived instance            |
+| --------------------- | --------------------------- |
+| `cabloy.test`         | `''` (the default instance) |
+| `acme.cabloy.test`    | `acme`                      |
+| `eu.acme.cabloy.test` | `acme.eu`                   |
+
+The default instance is an explicitly configured empty-name instance. It can be disabled or removed. Each non-empty derived instance name must also be explicitly configured and enabled before its hostname can serve application traffic. A missing, disabled, or deleted named instance does not fall back to the default instance.
+
+The Docker Nginx template preserves both the incoming `Host` and `X-Forwarded-Host`. This is necessary because Vona uses the forwarded host for host-sensitive URLs and subdomain instance resolution. Test through Nginx, not only by calling the app container directly.
+
+For the instance configuration shape and full resolution order, see [Multi-Instance and Instance Resolution](/backend/multi-instance-and-instance-resolution).
+
+## Origin HTTPS prerequisite
+
+Cloudflare TLS has two separate connections:
+
+```text
+Visitor <-> Cloudflare edge
+Cloudflare <-> origin Nginx
+```
+
+The shared Docker origin baseline listens on port 80 only. Verify the current Nginx template in your edition repository. Before enabling Cloudflare **Full (strict)**, provide a separately managed TLS-capable origin layer and a valid certificate that matches the origin hostname. For example, this can be an Nginx or ingress configuration managed by the deployment environment.
+
+Use Cloudflare **Full (strict)** for the production connection to the origin. Do not use Flexible mode: it leaves the Cloudflare-to-origin connection unencrypted and can produce incorrect scheme and security behavior. Enabling the orange cloud alone does not add HTTPS to the origin.
+
+For current Cloudflare requirements, see [Full (strict)](https://developers.cloudflare.com/ssl/origin-configuration/ssl-modes/full-strict/).
+
+## Stage 2: put Cloudflare in front of the origin
+
+After the origin is reachable with its TLS configuration:
+
+1. Create the DNS record for the base hostname, such as `example.com`, pointing to the origin server.
+2. Enable the record's orange-cloud proxy status.
+3. If subdomain instance routing is required, add the required instance records or a suitable wildcard record, such as `*.example.com`.
+4. Keep the origin proxy configuration forwarding the original `Host` and `X-Forwarded-Host` values to Vona.
+5. Set the deployment environment to the public URL when it must produce canonical absolute URLs:
+
+   ```dotenv
+   SERVER_SERVE_PROTOCOL=https
+   SERVER_SERVE_HOST=example.com
+   SERVER_SUBDOMAINOFFSET=2
+   ```
+
+The base hostname resolves to the empty-name/default instance. For example, `acme.example.com` resolves to `acme`; a deeper hostname such as `eu.acme.example.com` resolves to `acme.eu` and requires that explicitly configured instance.
+
+For current Cloudflare proxy-record behavior, see [Proxied DNS records](https://developers.cloudflare.com/dns/manage-dns-records/reference/proxied-dns-records/).
+
+## Cloudflare Cache Rule
+
+Configure one Cache Rule for the SSR origin:
+
+1. **If incoming requests match:** All incoming requests.
+2. **Cache eligibility:** Eligible for cache.
+3. **Edge TTL:** Use the origin `Cache-Control` header when present; bypass cache when it is absent.
+
+Do not add another Cache Rule or response-header override that replaces the origin `Cache-Control` value for these routes.
+
+This rule is intentionally small. It makes a response eligible for caching but still lets the SSR response header decide whether Cloudflare stores it. A `no-store` response remains non-cacheable, and normal Cloudflare cacheability safeguards still apply.
+
+For current Cache Rule settings, see [Cache Rules settings](https://developers.cloudflare.com/cache/how-to/cache-rules/settings/).
+
+## SSR cache contract
+
+Zova SSR writes the cache contract during rendering through `SSR_TRANSFERCACHE` and `SSR_TRANSFERCACHE_EXPIRES`. The current public Cabloy Basic baseline uses these defaults:
+
+| Flavor | Default settings                                          | SSR response header                                  | Cloudflare result with this rule                                |
+| ------ | --------------------------------------------------------- | ---------------------------------------------------- | --------------------------------------------------------------- |
+| Web    | `SSR_TRANSFERCACHE=true`, `SSR_TRANSFERCACHE_EXPIRES=10m` | `Cache-Control: public, max-age=600`                 | Eligible to cache for ten minutes, subject to Cloudflare policy |
+| Admin  | `SSR_TRANSFERCACHE=true`, `SSR_TRANSFERCACHE_EXPIRES=0`   | `Cache-Control: no-cache, no-store, must-revalidate` | Not stored                                                      |
+
+For Cabloy Start, verify the effective Web and Admin values in the licensed Start repository before creating the Cloudflare rule. The rule design remains the same: preserve and follow the origin `Cache-Control` response instead of replacing it.
+
+A route can override the flavor default through SSR route metadata. The Cloudflare rule follows the response contract; it does not replace it.
+
+For the public Basic environment-variable details, see [SSR Environment Variables](/frontend/ssr-env).
+
+## Deployment checks
+
+After the origin is running, verify the following before relying on Cloudflare traffic:
+
+1. The base hostname returns the expected default instance.
+2. Each configured subdomain resolves to its expected enabled instance.
+3. Nginx forwards the browser hostname instead of the literal value `localhost`.
+4. Web SSR returns the `Cache-Control` header expected from the active edition and flavor configuration. In the current Basic baseline, it is `public, max-age=600`.
+5. Admin SSR returns the `Cache-Control` header expected from the active edition and flavor configuration. In the current Basic baseline, it is `no-cache, no-store, must-revalidate`.
+6. After Cloudflare proxying is enabled, responses intended to be public-cacheable can be cached at the edge while responses marked `no-store` are not stored.

package/cabloy-docs/fullstack/openapi-to-sdk.md

@@ -68,6 +68,7 @@ For the deeper frontend perspective, see:
 If you want the shortest accurate mental model, use this forward chain:
 
 1. backend controller signatures define request and response entry surfaces
+   - command-style mutations that complete with Vona's wrapped `data: null` must declare `@Api.body(z.null())`; `Promise<void>` alone cannot preserve that generic type through runtime reflection
 2. backend DTO and entity fields shape named and shared contract structure
 3. validation rules and `v` helpers refine the machine-readable contract
 4. Vona emits OpenAPI output from those backend declarations

package/cabloy-docs/fullstack/tutorial-2-first-crud.md

@@ -95,6 +95,9 @@ As you inspect the generated files, pay attention to the division of responsibil
 
 This is the backend contract thread that later tutorials will extend with `level`, `mobile`, render metadata, OpenAPI output, and row actions.
 
+> [!NOTE]
+> The generated Admin CRUD actions explicitly require the `systemAdmin` role. If this resource should serve another audience, adjust the relevant controller action guards as well as any SSR menu visibility; changing the menu alone does not authorize an API.
+
 ## Verification
 
 1. make sure the local dev workflow is running:

package/package.json

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

package/vona/docker-compose-original/config/nginx/conf.d/nginx.conf

@@ -12,7 +12,7 @@ server {
     proxy_http_version 1.1;
     proxy_set_header X-Real-IP $remote_addr;
     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-    proxy_set_header X-Forwarded-Host $server_name;
+    proxy_set_header X-Forwarded-Host $http_host;
     proxy_set_header X-Forwarded-Proto $scheme;
     proxy_set_header Host $http_host;
     proxy_set_header X-NginX-Proxy true;

package/vona/env/.env

@@ -9,7 +9,7 @@ APP_VERSION = 5.0.0
 SERVER_KEYS = vona__1596889047267_3245
 SERVER_GLOBALPREFIX = /api
 SERVER_PUBLICDIR =
-SERVER_SUBDOMAINOFFSET = 1
+SERVER_SUBDOMAINOFFSET = 2
 SERVER_WORKERS =
 SERVER_LISTEN_HOSTNAME = 0.0.0.0
 SERVER_LISTEN_PORT = 7102

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

@@ -1,6 +1,6 @@
 {
   "name": "vona-cli",
-  "version": "1.1.129",
+  "version": "1.1.130",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona cli",
   "keywords": [

package/vona/packages-cli/cli-set-api/cli/templates/tools/crud/boilerplate/src/bean/ssrMenu.{{resourceName}}.ts_

@@ -20,6 +20,7 @@ export interface ISsrMenuOptions<%=argv.resourceNameCapitalize%> extends IDecora
         },
       },
       group: '<%=argv.ssrSiteGroupName%>',
+      roles: ['systemAdmin'],
     },
   },
   site: ['<%=argv.ssrSiteOnionName%>'],

package/vona/packages-cli/cli-set-api/cli/templates/tools/crudBasic/boilerplate/src/controller/{{resourceName}}.ts_

@@ -4,6 +4,8 @@ import type { IDecoratorControllerOptions } from 'vona-module-a-web';
 
 import { BeanBase } from 'vona';
 import { Api, Resource, v } from 'vona-module-a-openapiutils';
+import { z } from 'zod';
+import { Passport } from 'vona-module-a-user';
 import { Arg, Controller, Web } from 'vona-module-a-web';
 
 import type { Model<%=argv.resourceNameCapitalize%> } from '../model/<%=argv.resourceName%>.ts';
@@ -21,29 +23,36 @@ export interface IControllerOptions<%=argv.resourceNameCapitalize%> extends IDec
 export class Controller<%=argv.resourceNameCapitalize%> extends BeanBase {
   @Web.post()
   @Api.body(v.tableIdentity())
+  @Passport.systemAdmin()
   async create(@Arg.body() <%=argv.resourceName%>: Dto<%=argv.resourceNameCapitalize%>Create): Promise<TableIdentity> {
     return (await this.scope.service.<%=argv.resourceName%>.create(<%=argv.resourceName%>)).id;
   }
 
   @Web.get()
   @Api.body(Dto<%=argv.resourceNameCapitalize%>SelectRes)
+  @Passport.systemAdmin()
   async select(@Arg.filter(Dto<%=argv.resourceNameCapitalize%>SelectReq) params: IQueryParams<Model<%=argv.resourceNameCapitalize%>>): Promise<Dto<%=argv.resourceNameCapitalize%>SelectRes> {
     return await this.scope.service.<%=argv.resourceName%>.select(params);
   }
 
   @Web.get(':id')
   @Api.body(v.optional(), v.object(Dto<%=argv.resourceNameCapitalize%>View))
+  @Passport.systemAdmin()
   async view(@Arg.param('id', v.tableIdentity()) id: TableIdentity): Promise<Dto<%=argv.resourceNameCapitalize%>View | undefined> {
     return await this.scope.service.<%=argv.resourceName%>.view(id);
   }
 
   @Web.patch(':id')
-  async update(@Arg.param('id', v.tableIdentity()) id: TableIdentity, @Arg.body() <%=argv.resourceName%>: Dto<%=argv.resourceNameCapitalize%>Update) {
-    return await this.scope.service.<%=argv.resourceName%>.update(id, <%=argv.resourceName%>);
+  @Api.body(z.null())
+  @Passport.systemAdmin()
+  async update(@Arg.param('id', v.tableIdentity()) id: TableIdentity, @Arg.body() <%=argv.resourceName%>: Dto<%=argv.resourceNameCapitalize%>Update): Promise<void> {
+    await this.scope.service.<%=argv.resourceName%>.update(id, <%=argv.resourceName%>);
   }
 
   @Web.delete(':id')
-  async delete(@Arg.param('id', v.tableIdentity()) id: TableIdentity) {
-    return await this.scope.service.<%=argv.resourceName%>.delete(id);
+  @Api.body(z.null())
+  @Passport.systemAdmin()
+  async delete(@Arg.param('id', v.tableIdentity()) id: TableIdentity): Promise<void> {
+    await this.scope.service.<%=argv.resourceName%>.delete(id);
   }
 }

package/vona/packages-cli/cli-set-api/cli/templates/tools/crudBasic/boilerplate/test/{{resourceName}}.test.ts_

@@ -15,7 +15,24 @@ describe('<%=argv.resourceName%>.test.ts', () => {
         name: '__TomNew__',
         description: 'This is a test',
       };
-      // login
+      // role-less authenticated users cannot access generated admin actions
+      await app.bean.passport.signinMock();
+      try {
+        app.bean.passport.current!.roles = [];
+        const actions = ['create', 'select', 'view', 'update', 'delete'];
+        const permissions = await Promise.all(
+          actions.map(action =>
+            app.bean.permission.retrievePermissionAction(
+              '<%=argv.moduleInfo.relativeName%>:<%=argv.resourceName%>',
+              action,
+            ),
+          ),
+        );
+        assert.deepEqual(permissions, actions.map(() => false));
+      } finally {
+        await app.bean.passport.signout();
+      }
+      // login as system admin
       await app.bean.passport.signinMock();
       // create
       const <%=argv.resourceName%>Id = await app.bean.executor.performAction('post', '<%=argv.moduleActionPathRaw%>', { body: data });
@@ -24,15 +41,17 @@ describe('<%=argv.resourceName%>.test.ts', () => {
       const selectRes: Dto<%=argv.resourceNameCapitalize%>SelectRes = await app.bean.executor.performAction('get', '<%=argv.moduleActionPathRaw%>');
       assert.equal(selectRes.list.findIndex(item => item.name === data.name) > -1, true);
       // update
-      await app.bean.executor.performAction('patch', '<%=argv.moduleActionPathRaw%>/:id', {
+      const updateRes = await app.bean.executor.performAction('patch', '<%=argv.moduleActionPathRaw%>/:id', {
         params: { id: <%=argv.resourceName%>Id },
         body: dataUpdate,
       });
+      assert.equal(updateRes, null);
       // findOne
       let <%=argv.resourceName%>: Entity<%=argv.resourceNameCapitalize%> = await app.bean.executor.performAction('get', '<%=argv.moduleActionPathRaw%>/:id', { params: { id: <%=argv.resourceName%>Id } });
       assert.equal(<%=argv.resourceName%>.name, dataUpdate.name);
       // delete
-      await app.bean.executor.performAction('delete', '<%=argv.moduleActionPathRaw%>/:id', { params: { id: <%=argv.resourceName%>.id } });
+      const deleteRes = await app.bean.executor.performAction('delete', '<%=argv.moduleActionPathRaw%>/:id', { params: { id: <%=argv.resourceName%>.id } });
+      assert.equal(deleteRes, null);
       // findOne
       <%=argv.resourceName%> = await app.bean.executor.performAction('get', '<%=argv.moduleActionPathRaw%>/:id', { params: { id: <%=argv.resourceName%>.id } });
       assert.equal(<%=argv.resourceName%>, undefined);

package/vona/packages-cli/cli-set-api/cli/templates/tools/crudStart/boilerplate/src/controller/{{resourceName}}.ts_

@@ -4,6 +4,8 @@ import type { IDecoratorControllerOptions } from 'vona-module-a-web';
 
 import { BeanBase } from 'vona';
 import { Api, Resource, v } from 'vona-module-a-openapiutils';
+import { z } from 'zod';
+import { Passport } from 'vona-module-a-user';
 import { Arg, Controller, Web } from 'vona-module-a-web';
 
 import type { Model<%=argv.resourceNameCapitalize%> } from '../model/<%=argv.resourceName%>.ts';
@@ -21,29 +23,36 @@ export interface IControllerOptions<%=argv.resourceNameCapitalize%> extends IDec
 export class Controller<%=argv.resourceNameCapitalize%> extends BeanBase {
   @Web.post()
   @Api.body(v.tableIdentity())
+  @Passport.systemAdmin()
   async create(@Arg.body() <%=argv.resourceName%>: Dto<%=argv.resourceNameCapitalize%>Create): Promise<TableIdentity> {
     return (await this.scope.service.<%=argv.resourceName%>.create(<%=argv.resourceName%>)).id;
   }
 
   @Web.get()
   @Api.body(Dto<%=argv.resourceNameCapitalize%>SelectRes)
+  @Passport.systemAdmin()
   async select(@Arg.filter(Dto<%=argv.resourceNameCapitalize%>SelectReq) params: IQueryParams<Model<%=argv.resourceNameCapitalize%>>): Promise<Dto<%=argv.resourceNameCapitalize%>SelectRes> {
     return await this.scope.service.<%=argv.resourceName%>.select(params);
   }
 
   @Web.get(':id')
   @Api.body(v.optional(), v.object(Dto<%=argv.resourceNameCapitalize%>View))
+  @Passport.systemAdmin()
   async view(@Arg.param('id', v.tableIdentity()) id: TableIdentity): Promise<Dto<%=argv.resourceNameCapitalize%>View | undefined> {
     return await this.scope.service.<%=argv.resourceName%>.view(id);
   }
 
   @Web.patch(':id')
-  async update(@Arg.param('id', v.tableIdentity()) id: TableIdentity, @Arg.body() <%=argv.resourceName%>: Dto<%=argv.resourceNameCapitalize%>Update) {
-    return await this.scope.service.<%=argv.resourceName%>.update(id, <%=argv.resourceName%>);
+  @Api.body(z.null())
+  @Passport.systemAdmin()
+  async update(@Arg.param('id', v.tableIdentity()) id: TableIdentity, @Arg.body() <%=argv.resourceName%>: Dto<%=argv.resourceNameCapitalize%>Update): Promise<void> {
+    await this.scope.service.<%=argv.resourceName%>.update(id, <%=argv.resourceName%>);
   }
 
   @Web.delete(':id')
-  async delete(@Arg.param('id', v.tableIdentity()) id: TableIdentity) {
-    return await this.scope.service.<%=argv.resourceName%>.delete(id);
+  @Api.body(z.null())
+  @Passport.systemAdmin()
+  async delete(@Arg.param('id', v.tableIdentity()) id: TableIdentity): Promise<void> {
+    await this.scope.service.<%=argv.resourceName%>.delete(id);
   }
 }