gina 0.6.7 → 0.6.8

package/framework/{v0.6.7 → v0.6.8}/core/controller/controller.js

@@ -326,6 +326,99 @@ function formatAttachmentDisposition(filename) {
     return 'attachment; filename="' + String(filename).replace(/[\\"]/g, '\\$&') + '"';
 }
 
+/**
+ * Parse an HTTP `Range` request header against a known representation size.
+ *
+ * Honours a SINGLE `bytes=` range in its three RFC 9110 shapes — `a-b`,
+ * `a-` (open-ended) and `-n` (suffix: the last `n` bytes). Everything else —
+ * an absent/non-string header, another unit, a multi-range list, syntactic
+ * garbage, or `a-b` with `a > b` — returns `null`, which the caller treats as
+ * "ignore the header, serve the full 200" (RFC-sanctioned: a server MAY
+ * ignore Range). A syntactically valid range that matches no byte of the
+ * representation — `start >= size`, a `-0` suffix, or any range against a
+ * zero-length object — returns `{unsatisfiable: true}`, the caller's 416.
+ * A satisfiable range comes back `{start, end}` with `end` INCLUSIVE and
+ * clamped to `size - 1`, matching both the header semantics and the storage
+ * drivers' `getRange` contract, so no arithmetic sits between them.
+ *
+ * @function _parseRangeHeader
+ * @private
+ * @param {string} header - The raw `Range` header value.
+ * @param {number} size   - The representation size in bytes.
+ * @returns {object|null} `{start, end}` inclusive · `{unsatisfiable: true}` · `null` (ignore).
+ *
+ * @example
+ *  _parseRangeHeader('bytes=0-499', 1000);   // -> { start: 0, end: 499 }
+ *  _parseRangeHeader('bytes=-500', 1000);    // -> { start: 500, end: 999 }
+ *  _parseRangeHeader('bytes=0-1,5-9', 1000); // -> null (multi-range: full 200)
+ *  _parseRangeHeader('bytes=1000-', 1000);   // -> { unsatisfiable: true } (416)
+ */
+function _parseRangeHeader(header, size) {
+    if ( typeof(header) != 'string' ) {
+        return null;
+    }
+    var m = header.match(/^\s*bytes\s*=\s*(\d*)\s*-\s*(\d*)\s*$/);
+    if ( !m ) {
+        return null;
+    }
+    var startStr = m[1], endStr = m[2];
+    if ( startStr === '' && endStr === '' ) {
+        return null; // "bytes=-" is garbage
+    }
+    if ( startStr === '' ) {
+        // suffix form `-n`: the last n bytes
+        var n = parseInt(endStr, 10);
+        if ( n === 0 || size === 0 ) {
+            return { unsatisfiable: true }; // a -0 suffix matches no byte; empty matches none
+        }
+        var s = size - n;
+        return { start: (s > 0) ? s : 0, end: size - 1 };
+    }
+    var start = parseInt(startStr, 10);
+    if ( size === 0 || start >= size ) {
+        return { unsatisfiable: true };
+    }
+    var end = ( endStr === '' ) ? size - 1 : parseInt(endStr, 10);
+    if ( end < start ) {
+        return null; // last-byte-pos < first-byte-pos: invalid spec, ignore (RFC 9110)
+    }
+    return { start: start, end: Math.min(end, size - 1) };
+}
+
+/**
+ * Resolve the Content-Type a stored object is served with.
+ *
+ * The stored contentType is UPLOADER-supplied and stored verbatim (untrusted
+ * at the seam), so serving it back on the app's own origin is a stored-XSS
+ * vector: a declared `text/html`/`image/svg+xml` renders as active content
+ * and `nosniff` does not stop a DECLARED type. Fail-closed: active-content
+ * types downgrade to `application/octet-stream` unless the app passes an
+ * explicit `opts.contentType` — the app's informed choice is served verbatim.
+ *
+ * @function _resolveServedContentType
+ * @private
+ * @param {string} [optsContentType] - The caller's explicit choice; wins verbatim.
+ * @param {string} [metaContentType] - The stored, uploader-supplied MIME type.
+ * @returns {string} The Content-Type to serve.
+ *
+ * @example
+ *  _resolveServedContentType(null, 'image/png');       // -> 'image/png'
+ *  _resolveServedContentType(null, 'text/html');       // -> 'application/octet-stream'
+ *  _resolveServedContentType('image/svg+xml', 'x/y');  // -> 'image/svg+xml' (explicit)
+ */
+function _resolveServedContentType(optsContentType, metaContentType) {
+    if ( typeof(optsContentType) == 'string' && optsContentType !== '' ) {
+        return optsContentType;
+    }
+    if ( typeof(metaContentType) == 'string' && metaContentType !== '' ) {
+        if ( /(html|xml|svg|javascript|ecmascript)/i.test(metaContentType) ) {
+            return 'application/octet-stream';
+        }
+        return metaContentType;
+    }
+    return 'application/octet-stream';
+}
+
 /**
  * @class SuperController
  * @constructor
@@ -1806,7 +1899,10 @@ function SuperController(options) {
      * HTTP/1.1: response.write() with automatic chunked transfer-encoding
      *
      * The iterable should yield strings or Buffers. Objects are coerced via String().
-     * Upstream response headers (CORS, etc.) are preserved in the initial headers frame.
+     * Buffers pass through byte-exact on non-SSE content-types (SSE decodes them as
+     * UTF-8 text). HEAD requests answer headers-only — the iterable is never consumed.
+     * Upstream response headers (CORS, Content-Range, etc.) are preserved in the initial
+     * headers frame, and the delegate's own defaults yield to pre-set values.
      *
      * @param {AsyncIterable} asyncIterable - Source of chunks; typically an AI SDK stream
      * @param {string}        [contentType] - Response Content-Type (default: text/event-stream)
@@ -2472,6 +2568,20 @@ function SuperController(options) {
      *
      * if you are free to use the redirection [ code ] of your choice, we've set it to 301 by default
      *
+     * Add [ keep-params ] to carry the incoming request's query string onto the
+     * redirect target (#B352). Default is `false`: the target is used verbatim and the
+     * caller's query is dropped, which is the historical behaviour of every redirect
+     * route. Set it when the redirect is a path normalisation and must stay transparent
+     * to request state — the framework's own auto-generated `webroot@<bundle>` route
+     * does exactly that, which is why `/webroot?token=…` now lands on
+     * `/webroot/?token=…` instead of losing the parameter:
+     * { "control": "redirect", "path": "/documentation/", "keep-params": true }
+     *
+     * Only a LOCAL target inherits the query. An absolute [ url ] names another origin,
+     * and forwarding the caller's parameters there would disclose whatever the query
+     * carried to a third party, so the flag is ignored for the absolute form. If the
+     * target already carries a query the incoming one is appended with `&`.
+     *
      *
      * 2) By calling this.redirect(rule, [ignoreWebRoot]):
      * ------------------------------------------------
@@ -2793,6 +2903,51 @@ function SuperController(options) {
                 //path = local.req.headers.host + path
             }
 
+            // #B352 — `keep-params`: carry the incoming request's query string onto the
+            // redirect target. The option has been documented as a redirect-route key
+            // since the pre-GitHub import, but was never implemented: `keepParams` was
+            // read into a local above and then dropped, so EVERY redirect-control route
+            // silently discarded the caller's query.
+            //
+            // This is what made the framework's own auto-generated `webroot@<bundle>`
+            // route lossy (config.js — it now sets the flag): that route's `param.path`
+            // is a CONSTANT (the configured webroot), so nothing else could ever have
+            // carried the query, and a bare-webroot hit carrying a token or a redirect
+            // target — `/app?t=…` -> 302 `/app/` — arrived at the application with the
+            // parameter already gone. A path-normalisation redirect must be transparent
+            // to request state.
+            //
+            // Query source is `originalUrl || url`, the established idiom here (#B219,
+            // pauseRequest, server.js access logs): the isaac engine strips the query
+            // from `req.url` before controllers run and preserves the byte-exact
+            // incoming URL on `req.originalUrl` (stamped as its listener's first
+            // statement); express sets `originalUrl` natively. A request carrying
+            // neither (bare/harness) simply contributes no query.
+            //
+            // Deliberately narrow scope — LOCAL targets only. An absolute `param.url`
+            // names another origin, and forwarding the caller's parameters there would
+            // hand a third party whatever the query carried (session tokens, ids). An
+            // opt-in convenience flag must not be able to leak cross-origin, so the
+            // absolute form is excluded rather than trusted.
+            //
+            // Placement is load-bearing: it runs BEFORE the `inheritedData` block below,
+            // whose `?`-vs-`&` test must see the query appended here. On the wrong-method
+            // (HEAD -> GET, 303) path both mechanisms fire, so the target carries the
+            // query verbatim AND the `inheritedData` copy — redundant but consistent.
+            if ( keepParams && !(/\:\/\//).test(path) ) {
+                var _incomingUrl = local.req.originalUrl || local.req.url || '';
+                var _queryIndex  = _incomingUrl.indexOf('?');
+                if ( _queryIndex > -1 ) {
+                    // verbatim — already percent-encoded as received, so re-encoding
+                    // would corrupt it. CR/LF stripped: a Location built from client
+                    // input must not be able to split the response header.
+                    var _incomingQuery = _incomingUrl.substring(_queryIndex + 1).replace(/[\r\n]/g, '');
+                    if ( _incomingQuery ) {
+                        path += ( (/\?/).test(path) ? '&' : '?' ) + _incomingQuery;
+                    }
+                }
+            }
+
             var isPopinContext = false;
             if (
                 typeof(req.routing.param.isPopinContext) != 'undefined'
@@ -2816,11 +2971,29 @@ function SuperController(options) {
                     return;
                 }
 
+                // #B353 — HEAD is a SAFE method: it is GET without a response body, so a
+                // redirect must treat it exactly as it treats GET. This gate exists to stop
+                // an UNSAFE method being replayed against the target — its own warning says
+                // "A redirection is not permitted in this scenario", which is a
+                // POST/PUT/DELETE concern — but it tested `!== 'GET'`, so HEAD was swept in
+                // with them. Every consequence was wrong for a safe method: a warning on a
+                // route that explicitly lists HEAD in its own `method` list (the framework's
+                // auto-generated `webroot@<bundle>` route does), a 303 telling the client to
+                // re-issue as GET and fetch a body it deliberately did not ask for, and —
+                // because switching the method made `originalMethod !== req.method` — an
+                // `inheritedData` copy appended to the target that the same request as a GET
+                // never receives. Admitting HEAD converges it on GET: same status, same
+                // Location, no warning.
+                //
+                // Kept as string comparisons rather than a regex, per #P13 below, which
+                // deliberately moved this condition off `/GET/i.test()`.
+                var _reqMethod  = req.method.toUpperCase();
+                var _origMethod = originalMethod ? originalMethod.toUpperCase() : null;
                 // replaced: !/GET/i.test() (#P13)
                 if (
-                    req.method.toUpperCase() !== 'GET'
+                    ( _reqMethod !== 'GET' && _reqMethod !== 'HEAD' )
                     ||
-                    originalMethod && originalMethod.toUpperCase() !== 'GET'
+                    ( _origMethod && _origMethod !== 'GET' && _origMethod !== 'HEAD' )
                 ) { // trying to redirect using the wrong method ?
 
                     console.warn(new Error('Your are trying to redirect using the wrong method: `'+ req.method+'`.\nThis can often occur while redirecting from a controller to another controller or from a bundle to another.\nA redirection is not permitted in this scenario.\nDon\'t panic :)\nSwitching request method to `GET` method instead.\n').message);
@@ -3398,6 +3571,290 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
     }
 
 
+    /**
+     * Serve a stored object over HTTP with full Range support — the read-side
+     * companion of `store()`'s driver-routed upload path (#STO1).
+     *
+     * Terminal: renders the bytes (via `renderStream`) or ends the response
+     * itself (304/416), or routes through `throwError` (404/500). The whole
+     * HTTP protocol dance is owned here so applications never re-implement it:
+     *
+     *  - `stat()`-gated: an unknown/released key answers 404; on the `stream`
+     *    strategy a finalize-heal residue (row write failed, bytes readable)
+     *    also 404s until the idempotent finalize heals the row.
+     *  - Strong validators: `ETag: "<key>"` (storage keys are immutable — every
+     *    strategy publishes via temp+rename and no in-place mutation API
+     *    exists) + `Last-Modified` from the publish time.
+     *  - Conditional GET: `If-None-Match` matching the key ETag → 304, no
+     *    driver read.
+     *  - Range (GET only, gated on `driver.capabilities.ranges`): a single
+     *    `bytes=` range → 206 with `Content-Range`/exact `Content-Length`;
+     *    unsatisfiable → 416 + `Content-Range: bytes *\/<size>`; multi-range /
+     *    other units / garbage → the full 200 (RFC-sanctioned ignore).
+     *    `If-Range` honours the Range only on an exact validator match —
+     *    anything unevaluable degrades to the full 200, fail-safe.
+     *  - `Accept-Ranges: bytes` advertised whenever the driver can serve them.
+     *  - Content-Type: `opts.contentType` verbatim (the app's informed choice),
+     *    else the STORED type with active-content downgrade — it is
+     *    uploader-supplied, so `text\/html`/`svg`/`xml`/`javascript` fall back
+     *    to `application\/octet-stream` (stored-XSS fail-closed). Every
+     *    response carries `X-Content-Type-Options: nosniff`.
+     *  - Caching: `Cache-Control: private, max-age=31536000, immutable` by
+     *    default (correct for immutable-per-key objects; `private` keeps
+     *    shared caches out of the application's authorization), overridable
+     *    verbatim via `opts.cacheControl`.
+     *  - HEAD answers headers-only (full-size accounting, no driver read).
+     *  - OFFLOAD (`capabilities.offload`, the `s3` adapter): GET/HEAD answer
+     *    **307** to a short-lived presigned URL instead of proxying the bytes
+     *    — after the 304 check, with the facade's decisions riding the URL as
+     *    signed `response-*` overrides (the DOWNGRADED content type included,
+     *    so the stored-XSS guard holds when the provider serves). Range goes
+     *    with the client to the provider, which answers 206/416 natively. The
+     *    redirect itself is `no-store` (it outlives no signature); the
+     *    payload's caching policy rides `response-cache-control`.
+     *    `opts.offload: false` forces the proxy path (`get`/`getRange`) —
+     *    private buckets, IP-gated egress, or byte-level control.
+     *
+     * Works identically on both engines: headers/status ride `local.res`, and
+     * the byte emission is `renderStream`'s two arms.
+     *
+     * @param {string}  driverName            - The `settings.storage` driver name (as `store()` routed it).
+     * @param {string}  key                   - The opaque storage key (from the `store()` result slot).
+     * @param {object}  [opts]                - Serving options.
+     * @param {string}  [opts.contentType]    - Explicit Content-Type; served verbatim, bypasses the downgrade.
+     * @param {string}  [opts.cacheControl]   - Explicit Cache-Control; replaces the immutable default.
+     * @param {boolean} [opts.download]       - `true` → `Content-Disposition: attachment`.
+     * @param {string}  [opts.filename]       - Download filename (implies attachment); defaults to the stored originalName.
+     * @param {boolean} [opts.offload]        - `false` → proxy the bytes even on an offload-capable
+     *                                          driver (no redirect). Default: offload when the
+     *                                          driver can.
+     * @returns {void}
+     *
+     * @example
+     * // a document route: GET /files/:id — Range, 304 and HEAD handled for free
+     * this.download = function(req, res) {
+     *     var self = this;
+     *     var doc  = getDocFromDb(req.params.id);   // { storageKey, mime, name }
+     *     self.serveFromStorage('media', doc.storageKey, { contentType: doc.mime });
+     * };
+     *
+     * @example
+     * // force a download dialog with a safe filename
+     * self.serveFromStorage('media', record.storageKey, { download: true, filename: 'report-2026.pdf' });
+     */
+    this.serveFromStorage = function(driverName, key, opts) {
+        // #B31/#B38 family — released-response guard: a prior terminal exit
+        // nulled the per-request refs; a live request is unaffected.
+        if ( local.res == null ) {
+            return;
+        }
+        opts = opts || {};
+
+        var request  = local.req;
+        var response = local.res;
+        var method   = ( request && request.method ) ? request.method.toUpperCase() : 'GET';
+
+        var driver = null;
+        try {
+            driver = lib.storage.get(driverName);
+        } catch (acquireErr) {
+            // not configured / unknown driver — an app config error, never a 404
+            return self.throwError(response, 500, acquireErr);
+        }
+
+        driver.stat(key, function onServeStat(statErr, meta) {
+            // re-guard after the async hop (the #M1/#B37 discipline)
+            if ( local.res == null ) {
+                return;
+            }
+            if ( statErr ) {
+                return self.throwError(response, 500, statErr);
+            }
+            if ( !meta ) {
+                return self.throwError(response, 404, new Error('serveFromStorage(): no object for key `' + key + '` on driver `' + driverName + '`'));
+            }
+
+            var size         = meta.size;
+            var contentType  = _resolveServedContentType(opts.contentType, meta.contentType);
+            var etag         = '"' + key + '"';
+            var lastModified = ( typeof(meta.createdAt) == 'number' ) ? new Date(meta.createdAt).toUTCString() : null;
+            var rangesOn     = !!( driver.capabilities && driver.capabilities.ranges );
+
+            /**
+             * Headers every serve outcome shares (200/206/304/416/HEAD).
+             * Applied only once an outcome is decided, so a driver error can
+             * still route through `throwError` with no Range headers leaked.
+             *
+             * @inner
+             * @returns {void}
+             */
+            var setCommonHeaders = function() {
+                response.setHeader('x-content-type-options', 'nosniff');
+                response.setHeader('etag', etag);
+                if ( lastModified ) {
+                    response.setHeader('last-modified', lastModified);
+                }
+                if ( rangesOn ) {
+                    response.setHeader('accept-ranges', 'bytes');
+                }
+                response.setHeader('cache-control',
+                    ( typeof(opts.cacheControl) == 'string' && opts.cacheControl !== '' )
+                        ? opts.cacheControl
+                        : 'private, max-age=31536000, immutable'
+                );
+                if ( opts.download === true || typeof(opts.filename) == 'string' ) {
+                    // the stored originalName is uploader-supplied: strip control
+                    // chars so setHeader cannot throw on CR/LF (header injection)
+                    var _fname = String(opts.filename || meta.originalName || 'download').replace(/[\x00-\x1f\x7f]/g, '');
+                    response.setHeader('content-disposition', formatAttachmentDisposition(_fname));
+                }
+            };
+
+            // Conditional GET — If-None-Match vs the strong key ETag (weak
+            // comparison per RFC 9110, hence indexOf: a W/-prefixed echo matches).
+            var inm = ( request && request.headers ) ? request.headers['if-none-match'] : null;
+            if ( inm && ( method === 'GET' || method === 'HEAD' )
+                && ( inm === '*' || String(inm).indexOf(etag) > -1 )
+            ) {
+                setCommonHeaders();
+                response.statusCode = 304;
+                local.req = null; local.res = null; local.next = null;
+                return response.end();
+            }
+
+            // #STO1 s3 — OFFLOAD: an offload-capable driver hands the byte
+            // transfer to its provider through a short-lived presigned URL.
+            // Runs AFTER the 304 check (the key ETag needs no presign) and
+            // carries this facade's decisions into the PROVIDER's response as
+            // signed response-* overrides — the DOWNGRADED content type
+            // included, which is what keeps the stored-XSS guard intact when
+            // the provider serves the bytes. Range is deliberately NOT
+            // evaluated here: the client re-issues it against the redirect
+            // target and the provider answers 206/416 natively. 307 preserves
+            // the method (HEAD stays HEAD). The redirect itself is `no-store`
+            // — a cached redirect would outlive its signature — while the
+            // payload's caching policy rides response-cache-control.
+            var offloadOn = !!( driver.capabilities && driver.capabilities.offload ) && ( opts.offload !== false );
+            if ( offloadOn && ( method === 'GET' || method === 'HEAD' ) ) {
+                var wantsAttachment = ( opts.download === true || typeof(opts.filename) == 'string' );
+                driver.resolve(key, {
+                    contentType  : contentType,
+                    download     : wantsAttachment,
+                    filename     : wantsAttachment
+                        ? String(opts.filename || meta.originalName || 'download').replace(/[\x00-\x1f\x7f]/g, '')
+                        : undefined,
+                    cacheControl : ( typeof(opts.cacheControl) == 'string' && opts.cacheControl !== '' )
+                        ? opts.cacheControl
+                        : 'private, max-age=31536000, immutable'
+                }, function onServeResolve(resolveErr, resolved) {
+                    if ( local.res == null ) {
+                        return;
+                    }
+                    if ( resolveErr ) {
+                        return self.throwError(response, ( resolveErr.code === 'STORAGE_NO_OBJECT' ) ? 404 : 500, resolveErr);
+                    }
+                    if ( !resolved || resolved.kind !== 'url' || typeof(resolved.url) != 'string' ) {
+                        // capability said offload, resolve() answered something
+                        // else — a driver contract violation, surfaced loudly
+                        // rather than silently degraded to the proxy path.
+                        return self.throwError(response, 500, new Error('serveFromStorage(): driver `' + driverName + '` declares capabilities.offload but resolve() returned no `{kind:\'url\'}` — driver contract violation'));
+                    }
+                    response.setHeader('x-content-type-options', 'nosniff');
+                    response.setHeader('cache-control', 'private, no-store');
+                    response.setHeader('location', resolved.url);
+                    response.statusCode = 307;
+                    local.req = null; local.res = null; local.next = null;
+                    return response.end();
+                });
+                return;
+            }
+
+            // HEAD — full-size accounting, headers only, no driver read; the
+            // renderStream HEAD branch ends the response without a body.
+            if ( method === 'HEAD' ) {
+                setCommonHeaders();
+                response.setHeader('content-length', String(size));
+                response.statusCode = response.statusCode || 200;
+                return self.renderStream(null, contentType);
+            }
+
+            // Range evaluation — GET only, and only when the driver can serve
+            // ranges (capability-gated: an offloading adapter that cannot is
+            // transparently answered with the full 200).
+            var range = null;
+            if ( method === 'GET' && rangesOn && request && request.headers && request.headers.range ) {
+                var ifRange   = request.headers['if-range'];
+                var ifRangeOk = true;
+                if ( typeof(ifRange) == 'string' && ifRange !== '' ) {
+                    // exact validator match only; anything unevaluable → full 200
+                    ifRangeOk = ( ifRange === etag ) || ( lastModified != null && ifRange === lastModified );
+                }
+                if ( ifRangeOk ) {
+                    range = _parseRangeHeader(request.headers.range, size);
+                }
+            }
+
+            if ( range && range.unsatisfiable ) {
+                setCommonHeaders();
+                response.setHeader('content-range', 'bytes */' + size);
+                response.statusCode = 416;
+                local.req = null; local.res = null; local.next = null;
+                return response.end();
+            }
+
+            /**
+             * Apply the decided outcome's headers and stream the bytes.
+             * Runs only in a driver-success callback (headers-on-success).
+             *
+             * @inner
+             * @param {number} status       - 200 or 206.
+             * @param {object} extraHeaders - Outcome-specific headers.
+             * @param {object} readable     - The driver's byte stream.
+             * @returns {void}
+             */
+            var sendStream = function(status, extraHeaders, readable) {
+                if ( local.res == null ) {
+                    return;
+                }
+                setCommonHeaders();
+                for (var h in extraHeaders) {
+                    response.setHeader(h, extraHeaders[h]);
+                }
+                response.statusCode = status;
+                return self.renderStream(readable, contentType);
+            };
+
+            if ( range ) {
+                driver.getRange(key, range.start, range.end, function onServeRange(rErr, readable) {
+                    if ( local.res == null ) {
+                        return;
+                    }
+                    if ( rErr ) {
+                        // post-stat race (cas grace expiry, vanished file) → 404;
+                        // anything else is an I/O anomaly → 500
+                        return self.throwError(response, ( rErr.code === 'STORAGE_NO_OBJECT' ) ? 404 : 500, rErr);
+                    }
+                    sendStream(206, {
+                        'content-range'  : 'bytes ' + range.start + '-' + range.end + '/' + size,
+                        'content-length' : String(range.end - range.start + 1)
+                    }, readable);
+                });
+                return;
+            }
+
+            driver.get(key, function onServeGet(gErr, readable) {
+                if ( local.res == null ) {
+                    return;
+                }
+                if ( gErr ) {
+                    return self.throwError(response, ( gErr.code === 'STORAGE_NO_OBJECT' ) ? 404 : 500, gErr);
+                }
+                sendStream(200, { 'content-length': String(size) }, readable);
+            });
+        });
+    }
+
+
     /**
      * Store file(s) to a targeted directory - Will create target if new
      * You only need to provide the destination path
@@ -5973,17 +6430,40 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
 
     /**
      * Push a Server-Sent Events payload to connected clients.
-     * Targets the client whose `sessionID` matches the current session,
-     * or broadcasts to all active clients when no session is found.
      *
-     * @param {object|null} payload     - Data to push; falls back to `req[method].payload` when `null`
-     * @param {object}      [option]    - Push options (e.g. `{ section: '...' }`)
-     * @param {function}    [callback]  - `callback(err, result)`
+     * The recipient is decided SERVER-side and can never be chosen by the
+     * request body (#B364): an explicit `option.sessionID` wins, else the
+     * payload goes to the caller's own session. With neither — and without an
+     * explicit broadcast — this is a no-op that warns, because a push with no
+     * resolvable recipient is a bug, and the previous fail-OPEN answer to it
+     * was to send to everybody.
+     *
+     * Reaching every connected client requires `option.broadcast === true`,
+     * supplied by your code rather than inferred from a missing value.
+     *
+     * @param {object|null}  payload             - Data to push; falls back to `req[method].payload` when `null`
+     * @param {object}       [option]            - Push options, also forwarded to the transport (e.g. `{ compress: true }`)
+     * @param {string}       [option.sessionID]  - Explicit recipient session id; defaults to the caller's own session
+     * @param {boolean}      [option.broadcast]  - `true` (strictly) to reach every connected client
+     * @param {string}       [option.section]    - Section stamped onto the payload; falls back to `req[method].section`
+     * @param {function}     [callback]          - `callback(err, result)`
      * @returns {void}
+     *
+     * @example
+     * // to the caller's own session
+     * self.push({ event: 'saved' });
+     *
+     * @example
+     * // to a specific session your code selected
+     * self.push({ event: 'invited' }, { sessionID: invitee.sessionId });
+     *
+     * @example
+     * // to everyone — deliberate, never implicit
+     * self.push({ event: 'maintenance' }, { broadcast: true });
      */
     this.push = function(payload, option, callback) {
 
-        // #B38 — released-response guard (see #B31): push is a fire-and-forget broadcast
+        // #B38 — released-response guard (see #B31): push is a fire-and-forget send
         // over the SSE/engine.io clients; on a released request (per-request refs nulled by
         // a terminal exit) a no-op return is correct — the response this request would have
         // pushed to is already gone. Live requests are unaffected (guard skipped).
@@ -5993,11 +6473,34 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
 
         var req = local.req, res = local.res;
         var method  = req.method.toLowerCase();
-        // if no session defined, will push to all active clients
-        // resuming current session
-        var sessionId = ( typeof(req[method].sessionID) != 'undefined' ) ? req[method].sessionID : null;
-        // retrieve section if existing
-        var section = ( typeof(req[method].section) != 'undefined' ) ? req[method].section : null;
+
+        // #B364 — the recipient is NEVER read from the request body. It used to be
+        // (`req[method].sessionID`), which let a caller aim a push at any session by
+        // sending an id — and, when the id was absent, at EVERY connected client.
+        // Order: explicit server-supplied id → the caller's own session → nothing.
+        var broadcast = ( option != null && option.broadcast === true );
+        var sessionId = null;
+        if ( option != null && typeof(option.sessionID) == 'string' && option.sessionID !== '' ) {
+            sessionId = option.sessionID;
+        } else if ( typeof(req.sessionID) != 'undefined' && req.sessionID ) {
+            sessionId = req.sessionID;
+        } else if ( req.session != null && typeof(req.session.id) != 'undefined' && req.session.id ) {
+            sessionId = req.session.id;
+        }
+
+        // Fail CLOSED: no recipient and no explicit broadcast sends nothing at all.
+        if ( !broadcast && !sessionId ) {
+            console.warn('[CONTROLLER][ push ] no recipient: the request has no session and no `option.sessionID` was given, so nothing was sent. Pass `{ sessionID: <id> }` to target a session, or `{ broadcast: true }` to reach every connected client.');
+            return;
+        }
+
+        // retrieve section if existing — an explicit option wins over the request
+        var section = null;
+        if ( option != null && typeof(option.section) != 'undefined' ) {
+            section = option.section;
+        } else if ( typeof(req[method].section) != 'undefined' ) {
+            section = req[method].section;
+        }
 
         if (!payload) {
             payload     = null;
@@ -6028,20 +6531,27 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
             clients = self.serverInstance.eio.clients;
             if ( clients ) {
                 for (let s in clients) {
-                    if ( !clients[s].constructor.name == 'Socket' ) {
+                    // #B364 — was `!clients[s].constructor.name == 'Socket'`, which parses
+                    // as `(!name) == 'Socket'` and is therefore always false: the guard
+                    // never once skipped a non-socket entry.
+                    if ( clients[s].constructor.name !== 'Socket' ) {
                         continue;
                     }
 
                     if (
-                        // session filter
-                        sessionId
-                        && typeof(clients[s].sessionId) != 'undefined'
-                        && clients[s].sessionId == sessionId
+                        // every client, only when the caller asked for it
+                        broadcast
                         ||
-                        // send to all clients if no specific sessionId defined
-                        !sessionId
+                        // otherwise the resolved session, and nothing else
+                        (
+                            typeof(clients[s].sessionId) != 'undefined'
+                            && clients[s].sessionId == sessionId
+                        )
                     ) {
-                        clients[s].sendPacket("message", payload, options, callback);
+                        // #B364 — was `options`, an identifier that exists nowhere in this
+                        // scope: every call threw ReferenceError here before sending, so
+                        // push() had never delivered a packet in any published release.
+                        clients[s].sendPacket("message", payload, option, callback);
                     }
                 }
             }