@nocobase/plugin-ai 2.4.0-alpha.3 → 2.4.0-alpha.5

package/dist/ai/docs/nocobase/file-manager/stable-url.md

@@ -72,7 +72,7 @@ curl -L \
 - Do not persist `temporaryAccessToken` or use it as a sharing link
 - Do not cache the `302 Location` as a permanent URL because storage signatures can expire
 - Do not rewrite the app, data source, collection, ID, or extension in the path
-- Reverse proxies must forward the `/files/` route under `APP_PUBLIC_PATH` to NocoBase. For subpath deployments, keep a compatible root-level `/files/` route as well. Configurations generated by the NocoBase CLI include both routes automatically
+- Reverse proxies must forward the `/files/` route under `APP_PUBLIC_PATH` to NocoBase. For subpath deployments, keep a compatible root-level `/files/` route as well. Configurations generated by the NocoBase CLI include both routes automatically; for manually maintained configurations, see [Nginx Reverse Proxy](../nocobase-cli/production/reverse-proxy/nginx.md)
 - Deployments where the pages access the API cross-origin (with `API_BASE_URL` pointing to another origin) must add the page origin to `CORS_ORIGIN_WHITELIST`; otherwise the login cookie is never stored and stable URLs return `403` for lack of credentials. See [Environment Variables](../get-started/installation/env.md#api_base_url)
 - Use a different `hostname` for each independent NocoBase service instead of separating services only by port. Browser cookies are not isolated by port; see [Production Environment Deployment](../get-started/deployment/production.md)
 - Sub-apps in the same NocoBase deployment are distinguished by app name and do not need separate hostnames. However, an independent service on another port still needs hostname isolation if it contains a main app or sub-app with the same name

package/dist/ai/docs/nocobase/file-manager/storage/index.md

@@ -97,13 +97,13 @@ The file record directly returns the address generated by the storage service, f
 https://storage.example.com/path/to/file.png
 ```
 
-This URL does not pass through NocoBase and does not check the file record's view permissions. For local storage, it is a local static file address. For cloud storage, it is usually an object storage or CDN address.
+This URL does not check the file record's view permissions. For local storage, it is usually a legacy `/storage/uploads/` URL, which requires sign-in by default but does not check the individual file record again. For cloud storage, it is usually an object storage or CDN address whose access policy is controlled by that storage service.
 
 Select Original URL only when the caller cannot use a NocoBase URL—for example, when it cannot follow `302` redirects or explicitly requires an object storage or CDN address.
 
 :::warning Note
 
-After Original URL is selected, anyone with a valid URL can bypass NocoBase permission checks and access the file. If the URL has no signature or expiration, make sure the bucket and file allow public read access.
+After Original URL is selected, anyone with a valid URL can bypass NocoBase file-record permissions. For local storage, the legacy URL is still subject to the `/storage/uploads/` login check; exposing the upload directory directly through custom Nginx may bypass that check. For cloud storage, if the URL has no signature or expiration, make sure the bucket and file allow public read access.
 
 :::
 
@@ -115,6 +115,14 @@ This option does not change the storage service's own public-read configuration.
 
 Markdown, external pages, and third-party services can also use a public NocoBase URL. For external use, convert the path returned by the API into an absolute URL that includes the NocoBase domain, and make sure the caller can follow `302` redirects.
 
+:::warning Local storage behavior
+
+A local-storage NocoBase URL eventually redirects to `/storage/uploads/`. Selecting Allow public access skips file-record permissions at the `/files/` stage, but the legacy URL still requires sign-in by default. To make local files anonymously readable, also set `LEGACY_LOCAL_STORAGE_PUBLIC_ACCESS=true` and restart the application. This environment variable exposes the entire legacy `/storage/uploads/` path, not only the storage where Allow public access was selected, so assess all existing files before enabling it.
+
+When using custom Nginx, configure `auth_request` for `/storage/uploads/` as well. See [Nginx Reverse Proxy](../../nocobase-cli/production/reverse-proxy/nginx.md) for the complete configuration.
+
+:::
+
 ### How to choose
 
 | Use case | File URL | Allow public access |
@@ -125,7 +133,7 @@ Markdown, external pages, and third-party services can also use a public NocoBas
 
 :::warning Note
 
-[Local Storage](./local), [Amazon S3](./amazon-s3), [Aliyun OSS](./aliyun-oss), and [Tencent COS](./tencent-cos) do not generate temporary signed URLs. Even when NocoBase URL and file record permissions are enabled, anyone who has already obtained the storage service's original address can still access the file directly.
+[Local Storage](./local), [Amazon S3](./amazon-s3), [Aliyun OSS](./aliyun-oss), and [Tencent COS](./tencent-cos) do not generate temporary signed URLs. Even when NocoBase URL and file-record permissions are enabled, someone who has obtained the storage service's original address can bypass file-record permissions. Legacy local-storage URLs still require sign-in by default; access to an original cloud-storage URL depends on that service's public-read configuration.
 
 For contracts, identity documents, internal materials, or other files that should not be public, use [S3 Pro](./s3-pro) and refer to its dedicated access-control configuration.
 

package/dist/ai/docs/nocobase/file-manager/storage/local.md

@@ -5,11 +5,13 @@ Uploaded files will be saved in a local directory on the server's hard drive. Th
 
 :::warning Note
 
-Local Storage does not support private access. After a file is uploaded, NocoBase generates a directly accessible URL, and anyone who has that URL can access the file.
+Use `/files/` stable URLs for local files whenever possible so NocoBase can check the file record and the current role's view permission. Legacy `/storage/uploads/` URLs do not enforce record-level permissions, but Docker, the built-in Nginx, and Nginx configurations generated by the NocoBase CLI restrict them to signed-in users by default.
 
 If you need to store contracts, identity documents, internal materials, or other files that should not be public, use [S3 Pro](./s3-pro). If historical files already exist, see [Migrate to S3 Pro](./migrate-to-s3-pro.md).
 
-If you are not using Docker or the official nginx configuration and access local uploaded files through a custom proxy, make sure the `/storage/uploads/` path sets `X-Content-Type-Options: nosniff` and returns active content files such as `html`, `svg`, `xhtml`, and `pdf` as attachments. For details, see [Security guide: File storage](../../security/guide.md#file-storage).
+If custom Nginx serves local uploads through `alias`, its `/storage/uploads/` location must use `auth_request` to call the NocoBase auth endpoint. Otherwise, it bypasses the default login check. Also set `X-Content-Type-Options: nosniff` and return active content files such as `html`, `svg`, `xhtml`, and `pdf` as attachments. See [Nginx Reverse Proxy](../../nocobase-cli/production/reverse-proxy/nginx.md) for a complete example and sub-application configuration, and [Security guide: File storage](../../security/guide.md#file-storage) for the associated risks.
+
+If an existing integration depends on anonymous access to legacy URLs, set `LEGACY_LOCAL_STORAGE_PUBLIC_ACCESS=true` and restart the application. This compatibility switch affects only `/storage/uploads/` and does not change record-level permissions for `/files/`.
 
 :::
 

package/dist/ai/docs/nocobase/get-started/installation/docker-nginx.mdx

@@ -96,8 +96,11 @@ services:
 - `./storage` must be mounted into both the `app` and `nginx` containers so they can share proxy config, static assets, and uploaded files
 - The `nginx` container should wait until `nocobase.conf` is generated, then link it to `/etc/nginx/conf.d/default.conf` with `ln -sf`
 - The generated config forwards both the `/files/` route under `APP_PUBLIC_PATH` and the root-level `/files/` route to NocoBase for authenticated file previews and downloads
+- Before Nginx returns a legacy `/storage/uploads/` file through `alias`, the generated config uses `auth_request` to ask NocoBase to verify the login state; anonymous access returns `401` by default
 - If you use an external Nginx container, let the `nginx` container handle the host port mapping. For testing, you can start with `13000:80`; in production, you usually expose the host `80` and `443` ports directly, while the `app` service does not need to expose its port to the host
 
+If an existing program depends on anonymous access to `/storage/uploads/`, add `LEGACY_LOCAL_STORAGE_PUBLIC_ACCESS=true` to `app.environment` and restart the application container. Do not remove or rewrite the `auth_request` in the generated config; the auth endpoint uses this variable to decide whether anonymous access is allowed. This variable does not change record-level permissions for `/files/`.
+
 ## If you use a local host Nginx
 
 If your Nginx is installed directly on the host instead of running in a Docker container, it is better to use a separate `docker-compose.yml`. In this setup, the `app` service must expose a host port directly, and the proxy-related environment variables should use host-side values.
@@ -171,7 +174,7 @@ sudo systemctl reload nginx
 
 If your host Nginx does not use the `conf.d` directory, replace the link target with your own config path. Usually it is safer to keep `nocobase.conf` as a file included from the `http {}` context instead of copying its content manually.
 
-If you maintain Nginx yourself instead of using the generated config, make sure `/files/` and the corresponding route under `APP_PUBLIC_PATH` are forwarded to NocoBase before the SPA fallback rules. See [Nginx Reverse Proxy](../../nocobase-cli/production/reverse-proxy/nginx.md) for a complete example.
+If you maintain Nginx yourself instead of using the generated config, make sure `/files/` and the corresponding route under `APP_PUBLIC_PATH` are forwarded to NocoBase before the SPA fallback rules. When serving `/storage/uploads/` through `alias`, you must also configure `auth_request` so the static directory cannot bypass the application login check. See [Nginx Reverse Proxy](../../nocobase-cli/production/reverse-proxy/nginx.md) for a complete example.
 
 ## Related links
 

package/dist/ai/docs/nocobase/get-started/installation/docker.mdx

@@ -660,6 +660,8 @@ If you also want to enable HTTPS, configure `443` and the certificate on the hos
 
 The `location /` block in this root-path configuration also proxies `/api/`, `/ws`, and `/files/`. If you split static assets from application routes, make sure `/files/` is still forwarded to NocoBase and is not handled as a static directory.
 
+Before returning a legacy `/storage/uploads/` file, the built-in Nginx asks NocoBase to verify the login state; anonymous access returns `401` by default. If a program already depended on anonymous access to these legacy URLs before an upgrade, add `LEGACY_LOCAL_STORAGE_PUBLIC_ACCESS=true` to `app.environment` and restart the container. Keep forwarding this path from the host Nginx to the container. Do not expose the host upload directory directly with another `alias`, because that would bypass the check.
+
 ### Subpath deployment
 
 If you want to deploy the app under a subpath, such as `https://your_domain.com/nocobase/`, configure the `APP_PUBLIC_PATH` environment variable first:

package/dist/ai/docs/nocobase/get-started/installation/env.md

@@ -107,6 +107,18 @@ NocoBase uses cookies to maintain login state and to authorize [stable file URLs
 Prefer serving the pages and the API from the same origin through a reverse proxy and leaving `API_BASE_URL` empty.
 :::
 
+### LEGACY_LOCAL_STORAGE_PUBLIC_ACCESS
+
+Controls whether legacy local file URLs under `/storage/uploads/` allow anonymous access. The default is `false`, so only signed-in users can access them.
+
+If an existing integration depends on public access through these URLs, explicitly enable compatibility mode:
+
+```bash
+LEGACY_LOCAL_STORAGE_PUBLIC_ACCESS=true
+```
+
+Restart the application after changing this variable. It affects only legacy `/storage/uploads/` URLs and does not change record-level permissions for `/files/`. Public access may expose uploaded files, so enable it only after confirming that the files are safe to publish.
+
 ### CORS_ORIGIN_WHITELIST
 
 Whitelist of origins allowed to access the API cross-origin with credentials (cookies). Multiple origins are separated by commas. Empty by default.

package/dist/ai/docs/nocobase/nocobase-cli/production/reverse-proxy/caddy.md

@@ -135,7 +135,7 @@ Taking `test2` as an example, key directories related to Caddy usually include:
 In other words, handwritten configuration usually needs to cover at least the following types of entries:
 
 - `v`: Redirect `/v` to `/v/`
-- `uploads`: Expose upload directory
+- `uploads`: Expose the upload directory after NocoBase authentication
 - `dist`: Expose the front-end build product directory
 - `oauth well-known`: Handle OAuth discovery paths
 - `openid well-known`: Handle OpenID discovery paths
@@ -164,10 +164,31 @@ c.local.nocobase.com {
     }
 
     handle_path /storage/uploads/* {
-        root * NB_CLI_ROOT/test2/storage/uploads
-        header Cache-Control public
-        header X-Content-Type-Options nosniff
-        file_server
+        route {
+            request_header -X-NocoBase-Auth-Set-Cookie
+            forward_auth host.docker.internal:56575 {
+                uri /api/auth:checkLegacyFileAccess
+                header_up X-App {query.__appName}
+                copy_headers Set-Cookie>X-NocoBase-Auth-Set-Cookie
+            }
+
+            @refreshedAuth header X-NocoBase-Auth-Set-Cookie *
+            header @refreshedAuth Set-Cookie {header.X-NocoBase-Auth-Set-Cookie}
+            header Cache-Control "private, no-store"
+            header Content-Security-Policy sandbox
+            header X-Content-Type-Options nosniff
+            header Content-Disposition inline
+
+            @activeUploadedContent path_regexp activeUploadedContent (?i)\.(?:htm|html|pdf|svg|svgz|xht|xhtml|xml|xsl|xslt)$
+            header @activeUploadedContent Content-Disposition attachment
+            @download query download=1
+            header @download Content-Disposition attachment
+            @markdown path_regexp markdown (?i)\.md$
+            header @markdown Content-Type text/markdown
+
+            root * NB_CLI_ROOT/test2/storage/uploads
+            file_server
+        }
     }
 
     handle_path /dist/* {
@@ -258,6 +279,8 @@ This is usually less likely to miss details related to `/files/`, WebSockets, st
 
 :::warning Note
 
+URLs under `/storage/uploads/` are legacy local file URLs and must pass NocoBase sign-in authentication by default. Do not expose the upload directory with `file_server` alone, because that bypasses access control. The example above uses `forward_auth` to call the NocoBase auth endpoint before Caddy sends the file. Set `LEGACY_LOCAL_STORAGE_PUBLIC_ACCESS=true` and restart the application only when anonymous access is explicitly required for compatibility.
+
 `/files/` is an application route that must pass through NocoBase authorization. Do not handle it as a static directory or let it fall through to the SPA fallback. Forward it to the NocoBase backend and place the rule before `handle_path /*` and other front-end fallback rules.
 
 If `APP_PUBLIC_PATH=/nocobase/` is configured, also forward `/nocobase/files/*`. Keep the root-level `/files/*` rule for compatibility with existing file URLs.

package/dist/ai/docs/nocobase/nocobase-cli/production/reverse-proxy/nginx.md

@@ -111,6 +111,7 @@ in:
 - `NB_CLI_ROOT/test2/storage/...` The following are the application's own static resources and upload directories
 - `app.conf` can be changed, but the NocoBase managed block must be retained
 - `index-v1.html` and `index-v2.html` will automatically rewrite resource addresses according to the current env subpath, active client version, and `CDN_BASE_URL`
+- `maps-http.conf` and `uploads-location.conf` protect legacy `/storage/uploads/` URLs together: the former resolves the sub-application parameter, and the latter runs an `auth_request` login check before Nginx returns a local file
 
 :::warning note
 
@@ -154,6 +155,11 @@ location / {
 For a CLI-hosted application like `test2`, a structure closer to a real deployment would usually look like this:
 
 ```nginx
+map $request_uri $legacy_file_app {
+    default "";
+    ~[?&]__appName=(?<legacy_file_app_name>[A-Za-z0-9_-]+)(?:&|$) $legacy_file_app_name;
+}
+
 server {
     listen 80;
     server_name c.local.nocobase.com;
@@ -165,6 +171,19 @@ server {
     include NB_CLI_ROOT/.nocobase/proxy/nginx/snippets/mime-types.conf;
     include NB_CLI_ROOT/.nocobase/proxy/nginx/snippets/gzip.conf;
 
+    location = /_nocobase_legacy_file_auth {
+        internal;
+        proxy_pass http://127.0.0.1:56575/api/auth:checkLegacyFileAccess;
+        proxy_pass_request_body off;
+        proxy_set_header Content-Length "";
+        proxy_set_header Cookie $http_cookie;
+        proxy_set_header Authorization $http_authorization;
+        proxy_set_header X-App $legacy_file_app;
+        proxy_set_header X-Original-URI $request_uri;
+        proxy_set_header Host $final_host;
+        proxy_set_header X-Forwarded-Proto $upstream_x_forwarded_proto;
+    }
+
     location /storage/uploads/ {
         alias NB_CLI_ROOT/test2/storage/uploads/;
         include NB_CLI_ROOT/.nocobase/proxy/nginx/snippets/uploads-location.conf;
@@ -216,6 +235,8 @@ server {
 }
 ```
 
+The `map` directive must be placed in Nginx's `http {}` context, not inside `server {}` or `location {}`. It identifies a sub-application from the `__appName` query parameter in a legacy file URL. The `/api/` segment in `proxy_pass` must match the application's actual `API_BASE_PATH`; when `APP_PUBLIC_PATH` is configured, use the same prefix for both the upload location and auth endpoint.
+
 There are two key points here:
 
 - `NB_CLI_ROOT/.nocobase/proxy/nginx/...` The following are agent auxiliary files maintained by CLI
@@ -243,6 +264,10 @@ This is usually less likely to miss details related to `/files/`, WebSockets, st
 
 If `APP_PUBLIC_PATH=/nocobase/` is configured, also forward `/nocobase/files/`. Keep the root-level `/files/` rule for compatibility with existing file URLs.
 
+Legacy `/storage/uploads/` URLs also require sign-in by default. When serving files directly with `alias`, run an `auth_request` to NocoBase's `auth:checkLegacyFileAccess` endpoint first. Configuring only the static directory bypasses the login check. The `uploads-location.conf` snippet in the example already contains the `auth_request` directive; if you do not use the CLI snippets, add the equivalent logic to the upload location yourself.
+
+If an existing integration must access legacy URLs anonymously, set `LEGACY_LOCAL_STORAGE_PUBLIC_ACCESS=true` for the NocoBase application and restart it. The auth endpoint evaluates this setting, so do not regenerate or remove the Nginx `auth_request` configuration. The switch affects only `/storage/uploads/` and does not change record-level permissions for `/files/`.
+
 :::
 
 ## How to handle HTTPS

package/dist/ai/docs/nocobase/security/guide.md

@@ -213,17 +213,30 @@ If you need to store sensitive files, it is recommended to use a cloud storage s
 
 ![](https://static-docs.nocobase.com/202501031623549.png)
 
-For local storage or other public storage that can be accessed directly through same-origin application URLs, you should also pay extra attention to the risks introduced by active content files. Files such as `html`, `xhtml`, and `svg` may be parsed and executed directly by the browser. If an attacker can upload such a file and trick a user into opening it, the attacker may use your trusted application domain to host a malicious page or script.
+For local storage or other storage that can be accessed directly through same-origin application URLs, you should also pay extra attention to the risks introduced by active content files. Files such as `html`, `xhtml`, and `svg` may be parsed and executed directly by the browser. If an attacker can upload such a file and trick a user into opening it, the attacker may use your trusted application domain to host a malicious page or script.
 
 NocoBase upload validation does not trust the `Content-Type` sent by the request. It prefers the MIME type detected on the server side. A file extension only represents the filename and should not be treated as the authoritative file content type. Therefore, when serving public uploaded files, you also need to make sure the file access path has proper security response headers.
 
-If you deploy with Docker or use the nginx configuration generated by NocoBase, the upload directory already includes this protection: all uploaded files return `X-Content-Type-Options: nosniff`, and active content files such as `html`, `xhtml`, `svg`, `svgz`, and `pdf` are returned as downloads through `Content-Disposition: attachment`.
+If you deploy with Docker or use the nginx configuration generated by NocoBase, legacy `/storage/uploads/` URLs are restricted to signed-in users. All uploaded files also return `X-Content-Type-Options: nosniff`, and active content files such as `html`, `xhtml`, `svg`, `svgz`, and `pdf` are returned as downloads through `Content-Disposition: attachment`. New `/files/` URLs continue to enforce record-level file permissions.
+
+If an existing integration still depends on anonymous access to legacy URLs, set `LEGACY_LOCAL_STORAGE_PUBLIC_ACCESS=true` and restart the application to restore public access to `/storage/uploads/`. This compatibility switch is disabled by default, affects only legacy URLs, and does not change record-level permissions for `/files/`. Public access may expose uploaded files, so confirm that they contain no sensitive content before enabling it.
 
 If you use a custom proxy, CDN, object storage, or expose the local upload directory directly, make sure these rules are not bypassed. You can use the following nginx configuration as a reference:
 
 ```nginx
+location = /_nocobase_legacy_file_auth {
+    internal;
+    proxy_pass http://127.0.0.1:13000/api/auth:checkLegacyFileAccess;
+    proxy_pass_request_body off;
+    proxy_set_header Content-Length "";
+    proxy_set_header Cookie $http_cookie;
+    proxy_set_header Authorization $http_authorization;
+}
+
 location ~* ^/storage/uploads/(.*\.(?:htm|html|svg|svgz|xhtml|pdf))$ {
     alias /path/to/nocobase/storage/uploads/$1;
+    auth_request /_nocobase_legacy_file_auth;
+    add_header Cache-Control "private, no-store" always;
     add_header Content-Disposition "attachment" always;
     add_header X-Content-Type-Options "nosniff" always;
     autoindex off;
@@ -231,6 +244,8 @@ location ~* ^/storage/uploads/(.*\.(?:htm|html|svg|svgz|xhtml|pdf))$ {
 
 location /storage/uploads/ {
     alias /path/to/nocobase/storage/uploads/;
+    auth_request /_nocobase_legacy_file_auth;
+    add_header Cache-Control "private, no-store" always;
     add_header X-Content-Type-Options "nosniff" always;
     autoindex off;
 }