nexus-shared 3.1.0 → 3.2.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Bijay Adhikari
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Bijay Adhikari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -834,10 +834,47 @@ export const { GET, HEAD, POST, PUT, PATCH, DELETE } = createApiProxy({ token: r
   and CRUD then takes only those modules (`AppModule`), so `{ module: NexusModule.Reservation, … }` in an HR app is a
   type error. Without it, the modules are `NexusModule`.
 - **The proxy, on or off.** With `useProxy` (the default), the browser calls `/api/app/<module>/<path>` and the proxy
-  route sends it on to the module's root with the user's token, which never reaches the browser; it strips the app's
-  cookies and the backend's hop headers, refuses `..`, rewrites the backend's redirects, and answers failures the way
-  the backend does. Off, the browser calls each module's `browserRoot` (public) and the proxy serves none.
-  `proxies(module)` mixes the two, such as uploads straight to the Drive module and the rest through the proxy.
+  route sends it on to the module's root with the user's token, which never reaches the browser. Off, the browser
+  calls each module's `browserRoot` (public) and the proxy serves none. `proxies(module)` mixes the two, such as
+  uploads straight to the Drive module and the rest through the proxy.
+- **The proxy hides the backend.** To the browser the app is the backend, and nothing in an answer names the real one:
+  - **No redirect reaches the browser.** One that stays inside the module (the root's origin, or its host moved to
+    https by the backend's HTTPS redirection, under the root's path in any casing) is followed on the server as
+    `fetch` follows it: 307 and 308 keep the method and body, a 303 and a POST's 301 or 302 become a GET, up to
+    `maxRedirects` (3). Any other answers 502 `BACKEND_REDIRECT_REFUSED`: following it would carry the token elsewhere.
+  - **Response headers by an allowlist**, `DEFAULT_PROXY_RESPONSE_HEADERS` (Content-Type, Content-Disposition,
+    Content-Language, Content-Range, Accept-Ranges, Cache-Control, Expires, ETag, Last-Modified, Vary, Retry-After),
+    the Nexus backend's `X-Nexus-*`, and the names in `responseHeaders`. Server, X-Powered-By, X-AspNet-*,
+    X-SourceFiles, Via, Alt-Svc, Strict-Transport-Security, Report-To, NEL, CORS, Location, Link and WWW-Authenticate
+    never pass, even named; Set-Cookie only with `passCookies`. Every answer gets `X-Content-Type-Options: nosniff`,
+    and `Cache-Control: private, no-store` unless the backend said how to cache it.
+  - **Error pages replaced.** An error answer that is not JSON (an HTML or text page, a stack trace), JSON that is a
+    stack trace or repeats the user's token, or one over 1 MB, becomes the failure envelope with the backend's status
+    and plain words (`BACKEND_ERROR_PAGE`). JSON refusals (the Nexus envelope, problem details) and empty ones pass as
+    they came, so the backend's own words still reach the form.
+  - **The request.** The browser's own `X-Forwarded-*`, `Forwarded`, `X-Real-IP` and the like never go on, nor its
+    cookies, a method or path override (`X-HTTP-Method-Override`, `X-Original-URL`) or Next.js's own headers. The
+    proxy writes X-Forwarded-For (the last address the app received, which Next.js or the app's reverse proxy wrote;
+    `clientAddress` reads it elsewhere; an IPv4 or IPv6 address or nothing, never other text) and X-Forwarded-Host
+    and -Proto (the app's configured origin, else the request's). A module whose root is a path on the app (a pretend
+    backend) is called at this server's own host and port, over http: the request URL's, which Next.js builds from
+    where it listens. Never at the configured origin, so an app whose `origin` reads the Host header cannot let a client
+    choose another port on the machine; `serverApi`, which has no request, uses that `origin`, so build it from
+    configuration, or take the Host only when it names this server's own port. A body over `maxBodySize` (100 MB) is
+    refused with 413 before the backend sees it, and a page of another site cannot call through the proxy
+    (`Sec-Fetch-Site: cross-site`, other than a link followed) unless `allowCrossSite`.
+  - **A server call can say who the client is too.** `lastForwardedAddress` and `readIpAddress` (`nexus-shared/server`)
+    read the client's address as the proxy does, from anything with a `get` (Next.js's `headers()` included). The
+    template's `api-setup.ts` gives Identity calls, and only them, `X-Forwarded-For` and the browser's `User-Agent`
+    through `configureServerApi({ headers })`: sign-in leaves from the server, and Identity's rate limit counts per
+    address. Only Identity's, because reading the request makes a page render per request.
+  - **Refusals** are the Nexus envelope, `{ isSuccess: false, code, message, messageCode, errorCode, errorMessages }`
+    (`failure` builds another backend's; `PROXY_REFUSALS` lists the codes), and the real cause goes to the server's
+    log (`onProblem`, default `console.error`), never with the token or a query string.
+  - **Two things the proxy cannot do for an app.** Node.js does not trust a development certificate (ASP.NET Core's)
+    unless it starts with `NODE_USE_SYSTEM_CA=1`, so a module whose http root redirects to such an https port answers
+    502 until then, and the log says so. And Next.js keeps an X-Forwarded-For a client sent when nothing stands in
+    front of the app, so only behind a reverse proxy of its own is the client's address certain.
 - **One engine, two clients.** `api` and `serverApi` are two settings of `createApiClient`: it fills `{id}` in the path
   from `params` or the body, adds the query, headers, and token, waits up to `timeout` (60 s), tries a failed GET once
   more (a save never twice), and reads every answer as an `ApiResult` (`ok`, `status`, `result`, `message`,
@@ -881,7 +918,9 @@ export const { GET, HEAD, POST, PUT, PATCH, DELETE } = createApiProxy({ token: r
   active records' (`NormalListing`, `NormalPagination`), and `lists.flag`, `lists.trash`, `pages.trash`, … the others
   (`FlagListing`, `TrashListing`, `TrashPagination`, …), for the CRUD component.
 - `npm run test:api` checks the builder, routes, modules (another app's enum, the proxy on and off), the engine, the
-  server client, and the proxy; `scripts/browser-checks/api-calls.cjs` in the template checks `/demo/api`.
+  server client, and the proxy's routing; `npm run test:proxy` checks how the proxy hides the backend (redirects,
+  headers, error pages, forwarded headers, paths, the body limit, other sites, the log) against a fake backend;
+  `scripts/browser-checks/api-calls.cjs` in the template checks `/demo/api`.
 
 ### Data table
 

package/dist/Client.Index.d.ts

@@ -10,6 +10,7 @@ export * from "./Components/Documents/SplitButton.tsx";
 export * from "./Components/Documents/TabButtons.tsx";
 export * from "./Components/Forms/ApiForm.tsx";
 export * from "./Components/Forms/Crud.tsx";
+export * from "./Components/Forms/CrudHistory.tsx";
 export * from "./Components/Forms/CrudParts.tsx";
 export * from "./Components/Forms/ExcelImport.tsx";
 export * from "./Components/Forms/Form.tsx";
@@ -17,6 +18,7 @@ export * from "./Components/Forms/SubmitForm.tsx";
 export * from "./Components/Inputs/Calendar.tsx";
 export * from "./Components/Inputs/CheckBox.tsx";
 export * from "./Components/Inputs/CheckBoxGroup.tsx";
+export * from "./Components/Inputs/CodeBox.tsx";
 export * from "./Components/Inputs/DatePicker.tsx";
 export * from "./Components/Inputs/DateRangePicker.tsx";
 export * from "./Components/Inputs/DateTimePicker.tsx";
@@ -55,4 +57,5 @@ export * from "./Helpers/UserPreferences.ts";
 export * from "./Services/BrowserApi.ts";
 export * from "./Services/ChatApi.ts";
 export * from "./Services/ExcelApi.ts";
+export * from "./Services/JoinSources.ts";
 export * from "./Services/ThemeService.ts";

package/dist/Client.Index.js

@@ -13,6 +13,7 @@ export * from "./Components/Documents/SplitButton.js";
 export * from "./Components/Documents/TabButtons.js";
 export * from "./Components/Forms/ApiForm.js";
 export * from "./Components/Forms/Crud.js";
+export * from "./Components/Forms/CrudHistory.js";
 export * from "./Components/Forms/CrudParts.js";
 export * from "./Components/Forms/ExcelImport.js";
 export * from "./Components/Forms/Form.js";
@@ -20,6 +21,7 @@ export * from "./Components/Forms/SubmitForm.js";
 export * from "./Components/Inputs/Calendar.js";
 export * from "./Components/Inputs/CheckBox.js";
 export * from "./Components/Inputs/CheckBoxGroup.js";
+export * from "./Components/Inputs/CodeBox.js";
 export * from "./Components/Inputs/DatePicker.js";
 export * from "./Components/Inputs/DateRangePicker.js";
 export * from "./Components/Inputs/DateTimePicker.js";
@@ -60,4 +62,5 @@ export * from "./Helpers/UserPreferences.js";
 export * from "./Services/BrowserApi.js";
 export * from "./Services/ChatApi.js";
 export * from "./Services/ExcelApi.js";
+export * from "./Services/JoinSources.js";
 export * from "./Services/ThemeService.js";