nucleus-core-ts 0.10.2 → 0.10.3

package/dist/src/Client/Proxy/httpProxy.js

@@ -280,6 +280,24 @@ export function createHttpProxyHandler(config) {
         }
         return `${baseUrl}${finalPath}`;
     }
+    /**
+   * The caller's address, from the inbound chain when hops are trusted.
+   *
+   * `X-Forwarded-For` is appended left-to-right, so with N trusted proxies in
+   * front the caller is the entry N from the RIGHT. Counting from the right is
+   * what makes it unspoofable: a client can prepend anything to the left, but
+   * it cannot control what the trusted hops append after it.
+   *
+   * Returns undefined when the chain is too short to satisfy the configured
+   * hop count — a chain that does not reach means the deployment is not what
+   * the configuration says, and inventing an address there would be worse than
+   * having none.
+   */ function clientFromChain(req, hops) {
+        if (hops <= 0) return undefined;
+        const chain = (req.headers.get('x-forwarded-for') ?? '').split(',').map((one)=>one.trim()).filter(Boolean);
+        if (chain.length < hops) return undefined;
+        return chain[chain.length - hops];
+    }
     function buildHeaders(req, target, clientIp) {
         const headers = new Headers(req.headers);
         // Strip hop-by-hop headers (RFC 7230 §6.1) — these are connection-scoped and
@@ -321,9 +339,21 @@ export function createHttpProxyHandler(config) {
             'true-client-ip',
             'x-client-ip'
         ])headers.delete(h);
-        if (clientIp) {
-            headers.set('x-forwarded-for', clientIp);
-            headers.set('x-real-ip', clientIp);
+        /*
+     * With trusted hops configured, the CHAIN wins over the socket.
+     *
+     * The socket peer is only the client when this proxy is the edge. Behind an
+     * ingress it is the ingress pod, and overwriting the chain with it threw
+     * away the one value that identified the caller — so everything downstream
+     * keyed on the address saw a single visitor for the whole cluster.
+     *
+     * Still an OVERWRITE, never an append: what is written is a value derived
+     * from a position the client cannot reach, so a spoofed prefix on the left
+     * is discarded rather than forwarded.
+     */ const resolved = clientFromChain(req, config.trustedProxyHops ?? 0) ?? clientIp;
+        if (resolved) {
+            headers.set('x-forwarded-for', resolved);
+            headers.set('x-real-ip', resolved);
         } else {
             // Couldn't resolve the socket IP — do not forward a client-controlled value.
             headers.delete('x-forwarded-for');

package/dist/src/Client/Proxy/types.d.ts

@@ -142,6 +142,28 @@ export interface HttpProxyTarget {
 }
 export interface HttpProxyConfig {
     targets: HttpProxyTarget[];
+    /**
+     * How many proxies sit IN FRONT of this one, and are trusted.
+     *
+     * Default 0, which keeps the old behaviour: the socket peer is the client and
+     * `X-Forwarded-For` is overwritten with it. That is right when this proxy is
+     * the edge, and wrong the moment anything stands in front — behind a
+     * Kubernetes ingress the socket peer is the INGRESS POD, so every request in
+     * the cluster arrives with one address and everything keyed on it collapses
+     * into a single bucket.
+     *
+     * Measured on a live install: 353 captcha challenges over 58 hours all
+     * attributed to `10.233.104.64`, 50 of them refused by a 10-per-minute
+     * per-IP limit, which during the morning sign-in rush meant the login page
+     * could not load a challenge at all.
+     *
+     * Set to the number of trusted hops and the client address is read from the
+     * inbound chain instead: `X-Forwarded-For` is a list appended left-to-right,
+     * so the caller is the entry `trustedProxyHops` from the RIGHT. Counting from
+     * the right is what makes it unspoofable — a client can prepend whatever it
+     * likes to the left, but it cannot control what the trusted hops append.
+     */
+    trustedProxyHops?: number;
     debug?: boolean;
     onError?: (error: Error, path: string, status?: number) => void;
     onRequest?: (path: string, target: string) => void;

package/dist/src/Nucleus/index.d.ts

@@ -29,6 +29,8 @@ export { createTenantRoutes } from './routes/tenant';
  * Read by `createNucleusServer`, which puts it on every handler's context.
  */
 export declare function getMountedRuntime(): unknown;
+/** @see recordResolvedOptions — the config AFTER a path was read and parsed. */
+export declare function getResolvedOptions(): unknown;
 export declare function getMountedRouteGroups(): RouteGroup[];
 export declare function getMountedSocket(): WebSocketRoute | null;
 export declare function getMountedStaticAssets(): string | null;

package/dist/src/Nucleus/routes/shared/bodyCeiling.d.ts

@@ -33,13 +33,42 @@ export declare function requiredBodyCeiling(input: {
  * configuration promises, or `null` when it can.
  *
  * Deliberately a full instruction rather than a warning. "Body size may be too
- * small" sends somebody reading source; naming the constructor argument and the
- * number ends it.
+ * small" sends somebody reading source; naming the setting and the number ends
+ * it.
+ *
+ * The instruction used to name Elysia's constructor, which stopped existing at
+ * 0.10 — so every upgraded install logged an ERROR whose one actionable
+ * sentence was impossible to act on. A boot error that cannot be obeyed teaches
+ * people to ignore boot errors.
  */
 export declare function bodyCeilingComplaint(input: {
     configured: number | null | undefined;
     required: number | null;
 }): string | null;
+/**
+ * What to hand `Bun.serve` as `maxRequestBodySize`, or `undefined` to leave
+ * Bun's default alone.
+ *
+ * This is HEADROOM, not enforcement, and the difference is the whole rule.
+ *
+ * Handing Bun the product's limit makes Bun answer first — a bare
+ * connection-level 413, no content-type, no body — instead of the guard's
+ * envelope. That is why the server passes it nothing by default. But Bun still
+ * cuts at 128 MiB before any guard runs, so an install advertising 1 GB uploads
+ * had them severed with nothing to show, and no way to raise it: this path
+ * forwarded nothing, and the boot warning told the host to construct an Elysia
+ * that no longer exists.
+ *
+ * So: never below what the guard enforces, never below what storage advertises,
+ * and unset whenever neither exceeds Bun's own default. Bun's number then sits
+ * at or above every limit the product applies, which leaves the guard as the
+ * first responder for everything it refuses — the envelope survives — while
+ * Bun stops severing uploads the product means to accept.
+ */
+export declare function bunBodyCeilingFor(input: {
+    storageRequired: number | null;
+    guardCeiling: number | undefined;
+}): number | undefined;
 /**
  * The sentence to print when the POD cannot carry what the configuration
  * promises, or `null` when it can.

package/dist/src/Server/routeRecording.d.ts

@@ -99,6 +99,22 @@ export declare function getRecordedSwagger(): unknown;
 export declare function recordRuntime(runtime: unknown): void;
 /** What `recordRuntime` last recorded, or undefined when nothing did. */
 export declare function getMountedRuntime(): unknown;
+/**
+ * The config AFTER it was resolved, which is not the config the host passed.
+ *
+ * `config.options` may be an object or a PATH to a JSON file. When it is a
+ * path, `buildNucleus` reads and parses it, and everything inside — the
+ * `security` block among it — exists only in there. `createNucleusServer`
+ * needed one of those settings and could only see the un-resolved form, so a
+ * host that passed a path silently ran without its request-body ceiling: the
+ * setting was in the file, read by the plugin, and invisible to the server.
+ *
+ * Recorded rather than returned from `buildNucleus`, to keep the one channel
+ * these two modules already use instead of opening a second.
+ */
+export declare function recordResolvedOptions(options: unknown): void;
+/** What `recordResolvedOptions` last recorded, or null when nothing did. */
+export declare function getResolvedOptions(): unknown;
 export declare function recordStaticAssets(assetsPath: string): void;
 export declare function getRecordedStaticAssets(): string | null;
 export declare function recordBootStep(step: BootStep): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nucleus-core-ts",
-  "version": "0.10.2",
+  "version": "0.10.3",
   "description": "Production-ready, enterprise-grade TypeScript framework for building multi-tenant APIs",
   "author": "Hidayet Can Özcan <hidayetcan@gmail.com>",
   "license": "SEE LICENSE IN LICENSE",