@lensmcp/cluster 1.11.0 → 1.13.0

package/executors/gateway/runtime/dev-auth.d.ts

@@ -0,0 +1,9 @@
+import type * as http from 'node:http';
+import type { Attrs } from './types';
+/** Verify the end-user JWT and return its claims, or undefined. */
+export declare function verifyDevJwt(req: http.IncomingMessage): Record<string, unknown> | undefined;
+/** Stamp verified identity onto the forwarded request — tenant from the `tid` CLAIM, never a client header. */
+export declare function stampIdentity(req: http.IncomingMessage, claims: Record<string, unknown>): void;
+/** Build the ABAC attribute bag from the verified claims + request envelope. */
+export declare const devAttrs: (req: http.IncomingMessage, claims: Record<string, unknown>) => Attrs;
+//# sourceMappingURL=dev-auth.d.ts.map

package/executors/gateway/runtime/dev-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-auth.d.ts","sourceRoot":"","sources":["../../../../../../libs/cluster/src/executors/gateway/runtime/dev-auth.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,KAAK,IAAI,MAAM,WAAW,CAAC;AACvC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC,mEAAmE;AACnE,wBAAgB,YAAY,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAiC3F;AAED,+GAA+G;AAC/G,wBAAgB,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAQ9F;AAED,gFAAgF;AAChF,eAAO,MAAM,QAAQ,GAAI,KAAK,IAAI,CAAC,eAAe,EAAE,QAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,KAKpF,CAAC"}

package/executors/gateway/runtime/dev-auth.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.devAttrs = void 0;
+exports.verifyDevJwt = verifyDevJwt;
+exports.stampIdentity = stampIdentity;
+/**
+ * Dev edge auth (HS256), mirroring the prod gateway: verify the end-user token, then stamp the
+ * trusted identity headers the services read (via GatewayTrustGuard). RS256/JWKS is prod's job;
+ * dev shares the `AUTH_JWT_SECRET` the auth host signs with. Pure functions.
+ */
+const node_crypto_1 = require("node:crypto");
+/** Verify the end-user JWT and return its claims, or undefined. */
+function verifyDevJwt(req) {
+    const secret = process.env['AUTH_JWT_SECRET'] ?? 'tetros-dev-secret';
+    const auth = String((Array.isArray(req.headers['authorization']) ? req.headers['authorization'][0] : req.headers['authorization']) ?? '');
+    if (!auth.startsWith('Bearer '))
+        return undefined;
+    const [h, p, s] = auth.slice(7).split('.');
+    if (!h || !p || !s)
+        return undefined;
+    // An IdP that signs ASYMMETRIC (RS256 + JWKS — e.g. tetros's auth host) does NOT use the HS256 dev
+    // shared-secret this dev edge assumed. The PROD gateway verifies RS256 via jwks-verify; in dev we
+    // DECODE + exp-check the claims (no signature check) — the gateway is the only local ingress, the token
+    // came from the trusted local IdP, and a dev IdP's ephemeral per-pod keys make in-cluster JWKS
+    // verification unreliable. (The HS256 path below stays for services using the shared-secret convention.)
+    let alg;
+    try {
+        alg = JSON.parse(Buffer.from(h, 'base64url').toString())['alg'];
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof alg === 'string' && alg !== 'HS256') {
+        try {
+            const rsClaims = JSON.parse(Buffer.from(p, 'base64url').toString());
+            if (typeof rsClaims['exp'] === 'number' && Date.now() / 1000 > rsClaims['exp'])
+                return undefined;
+            return rsClaims;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    const expected = (0, node_crypto_1.createHmac)('sha256', secret).update(`${h}.${p}`).digest('base64url');
+    const a = Buffer.from(s);
+    const b = Buffer.from(expected);
+    if (a.length !== b.length || !(0, node_crypto_1.timingSafeEqual)(a, b))
+        return undefined;
+    try {
+        const claims = JSON.parse(Buffer.from(p, 'base64url').toString());
+        if (typeof claims['exp'] === 'number' && Date.now() / 1000 > claims['exp'])
+            return undefined;
+        return claims;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Stamp verified identity onto the forwarded request — tenant from the `tid` CLAIM, never a client header. */
+function stampIdentity(req, claims) {
+    const set = (k, v) => { if (v !== undefined && v !== null && v !== '')
+        req.headers[k] = String(v); };
+    set('x-user-id', claims['sub']);
+    set('x-tenant-id', claims['tid']);
+    const roles = claims['roles'];
+    if (Array.isArray(roles) && roles.length)
+        req.headers['x-user-roles'] = roles.map(String).join(',');
+    const perms = claims['perms'];
+    if (Array.isArray(perms) && perms.length)
+        req.headers['x-user-permissions'] = perms.map(String).join(',');
+}
+/** Build the ABAC attribute bag from the verified claims + request envelope. */
+const devAttrs = (req, claims) => ({
+    ...claims,
+    ip: req.socket.remoteAddress ?? '',
+    method: (req.method ?? 'GET').toUpperCase(),
+    path: (req.url ?? '/').split('?')[0],
+});
+exports.devAttrs = devAttrs;

package/executors/gateway/runtime/discovery.d.ts

@@ -0,0 +1,17 @@
+import type { Route, ServiceCtl, SockPool } from './types';
+/** Round-robin over the pool's sockets, rescanning the dir when the cache ages out. */
+export declare function pickSock(pool: SockPool, scanTtlMs?: number): string | undefined;
+/** Extract the port from an `upstream` URL like `http://localhost:5173`. */
+export declare function lensPortFromUpstream(upstream?: string): number | undefined;
+/**
+ * Read every project's `cluster` (or legacy `davnx`) declaration and build
+ * the route table: host routes first (plus auto `internal.<host>` for pod
+ * services), the `default` catch-all last.
+ */
+export declare function discoverRoutes(rootDir: string, projects: Record<string, {
+    root: string;
+}>, sockBaseDir?: string): {
+    routes: Route[];
+    services: ServiceCtl[];
+};
+//# sourceMappingURL=discovery.d.ts.map

package/executors/gateway/runtime/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../../../../../libs/cluster/src/executors/gateway/runtime/discovery.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAoC,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAE7F,uFAAuF;AACvF,wBAAgB,QAAQ,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,SAAO,GAAG,MAAM,GAAG,SAAS,CAa7E;AAED,4EAA4E;AAC5E,wBAAgB,oBAAoB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAI1E;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,EAC1C,WAAW,SAAc,GACxB;IAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAAC,QAAQ,EAAE,UAAU,EAAE,CAAA;CAAE,CAyD7C"}

package/executors/gateway/runtime/discovery.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pickSock = pickSock;
+exports.lensPortFromUpstream = lensPortFromUpstream;
+exports.discoverRoutes = discoverRoutes;
+const tslib_1 = require("tslib");
+/**
+ * Route discovery + socket-pool round-robin. Pure (fs reads only): reads every
+ * project's `cluster` (or legacy `davnx`) declaration and builds the route table.
+ */
+const fs = tslib_1.__importStar(require("node:fs"));
+const os = tslib_1.__importStar(require("node:os"));
+const path = tslib_1.__importStar(require("node:path"));
+const manifest_1 = require("../manifest");
+/** Round-robin over the pool's sockets, rescanning the dir when the cache ages out. */
+function pickSock(pool, scanTtlMs = 1500) {
+    const now = Date.now();
+    if (now - pool.scannedAt > scanTtlMs) {
+        try {
+            pool.socks = fs.readdirSync(pool.dir)
+                .filter((f) => /^child-\d+\.sock$/.test(f))
+                .map((f) => path.join(pool.dir, f));
+        }
+        catch {
+            pool.socks = [];
+        }
+        pool.scannedAt = now;
+    }
+    if (pool.socks.length === 0)
+        return undefined;
+    pool.idx = (pool.idx + 1) % pool.socks.length;
+    return pool.socks[pool.idx];
+}
+/** Extract the port from an `upstream` URL like `http://localhost:5173`. */
+function lensPortFromUpstream(upstream) {
+    if (!upstream)
+        return undefined;
+    const m = /:(\d+)/.exec(upstream);
+    return m ? Number(m[1]) : undefined;
+}
+/**
+ * Read every project's `cluster` (or legacy `davnx`) declaration and build
+ * the route table: host routes first (plus auto `internal.<host>` for pod
+ * services), the `default` catch-all last.
+ */
+function discoverRoutes(rootDir, projects, sockBaseDir = os.tmpdir()) {
+    const routes = [];
+    const services = [];
+    let defaultRoute;
+    for (const [name, p] of Object.entries(projects)) {
+        let decl;
+        try {
+            const raw = JSON.parse(fs.readFileSync(path.join(rootDir, p.root, 'project.json'), 'utf8'));
+            decl = raw.cluster ?? raw.davnx;
+        }
+        catch {
+            continue;
+        }
+        if (!decl)
+            continue;
+        let pool;
+        let svc;
+        let target;
+        let lens;
+        if (decl.service) {
+            // `lens` applies to FRONTEND apps only; a pod service is already
+            // instrumented by the serve executor's node-instrumentation graft.
+            if (decl.lens)
+                console.warn(`[gateway] ${name}: cluster.lens is ignored for pod (service) decls — backends are instrumented by serve-hmr.`);
+            pool = { dir: path.join(sockBaseDir, `${decl.service}-devserver`), socks: [], idx: -1, scannedAt: 0 };
+            svc = { project: name, decl, pool, state: 'down', lastUsed: Date.now(), inflight: 0, lastScaleAt: 0 };
+            services.push(svc);
+        }
+        else if (decl.lens) {
+            // Lens-mode frontend: the gateway SPAWNS this app's Vite + instrumentation
+            // (deterministically on `port`) and upstreams to it. One LensFrontend per
+            // project is SHARED across its host/default routes (so the spawn fires once).
+            const port = decl.port ?? lensPortFromUpstream(decl.upstream) ?? 5173;
+            target = `http://localhost:${port}`;
+            lens = { project: name, projectRoot: path.join(rootDir, p.root), port };
+        }
+        else {
+            target = decl.upstream ?? (decl.port ? `http://localhost:${decl.port}` : undefined);
+            if (!target) {
+                console.warn(`[gateway] ${name}: no service/upstream/port — skipped.`);
+                continue;
+            }
+        }
+        const base = { project: name, prependPrefix: decl.prependPrefix, target, pool, svc, prefix: decl.path, auth: decl.auth, lens };
+        if (decl.host) {
+            routes.push({ ...base, host: decl.host });
+            // internal.<host>: east-west traffic, same pods, NO middleware.
+            if (pool && decl.internalHost !== false) {
+                routes.push({
+                    ...base,
+                    host: typeof decl.internalHost === 'string' ? decl.internalHost : `internal.${decl.host}`,
+                    internal: true,
+                });
+            }
+        }
+        if (decl.default)
+            defaultRoute = { ...base, prefix: undefined };
+    }
+    if (defaultRoute)
+        routes.push(defaultRoute);
+    // specificity sort (shared with prod): host+path beats host-only beats
+    // catch-all — so a path-mounted service (api.x/channels) wins over the
+    // host's owner (api.x → api).
+    (0, manifest_1.sortBySpecificity)(routes);
+    return { routes, services };
+}

package/executors/gateway/runtime/edge.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Edge primitives shared by the HTTP handler and the WS upgrade: the localized
+ * error envelope, the CORS headers, and the trust-header allowlist. Pure (no
+ * runtime state) so both pipelines and any hook can use them.
+ */
+import type * as http from 'node:http';
+import { type GatewayErrorReason } from '../gateway-errors';
+/**
+ * Send a gateway-generated edge error as the JSON envelope `{ key, status, traceId, message? }` (NOT
+ * `text/plain`) + an `x-request-id` header — the SAME localized contract a service returns, so a browser
+ * app renders `t(key)` and surfaces the trace id. Mirrors the prod gateway's `sendError`.
+ */
+export declare const sendError: (res: http.ServerResponse, req: http.IncomingMessage, status: number, reason: GatewayErrorReason, detail?: string) => void;
+/**
+ * The gateway OWNS these headers — strip any client-supplied copy at ingress so identity + trust can
+ * only originate from the gateway (mirrors the prod gateway's stripTrust). Applied at the very top of
+ * BOTH the HTTP handler and the WS upgrade.
+ */
+export declare const GATEWAY_OWNED_HEADERS: string[];
+/** Reflect the request Origin back with credentials — the gateway is the edge CORS authority. */
+export declare const cors: (req: http.IncomingMessage, res: http.ServerResponse) => void;
+/**
+ * Answer a CORS preflight (OPTIONS) at the edge: reflect CORS + 204 with the allowed `methods` and the
+ * requested headers echoed back. `methods` differs by caller — the no-route host-root uses the narrow
+ * `GET,HEAD,OPTIONS`; a routed path uses the wide verb list.
+ */
+export declare const corsPreflight: (req: http.IncomingMessage, res: http.ServerResponse, methods: string) => void;
+/** Allowed-methods lists for the two preflight sites. */
+export declare const PREFLIGHT_METHODS_NOROUTE = "GET,HEAD,OPTIONS";
+export declare const PREFLIGHT_METHODS_ROUTED = "GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS";
+//# sourceMappingURL=edge.d.ts.map

package/executors/gateway/runtime/edge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge.d.ts","sourceRoot":"","sources":["../../../../../../libs/cluster/src/executors/gateway/runtime/edge.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,KAAK,IAAI,MAAM,WAAW,CAAC;AACvC,OAAO,EAIL,KAAK,kBAAkB,EACxB,MAAM,mBAAmB,CAAC;AAE3B;;;;GAIG;AACH,eAAO,MAAM,SAAS,GACpB,KAAK,IAAI,CAAC,cAAc,EACxB,KAAK,IAAI,CAAC,eAAe,EACzB,QAAQ,MAAM,EACd,QAAQ,kBAAkB,EAC1B,SAAS,MAAM,KACd,IAIF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,UAAyG,CAAC;AAE5I,iGAAiG;AACjG,eAAO,MAAM,IAAI,GAAI,KAAK,IAAI,CAAC,eAAe,EAAE,KAAK,IAAI,CAAC,cAAc,KAAG,IAK1E,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,KAAK,IAAI,CAAC,eAAe,EAAE,KAAK,IAAI,CAAC,cAAc,EAAE,SAAS,MAAM,KAAG,IAOpG,CAAC;AAEF,yDAAyD;AACzD,eAAO,MAAM,yBAAyB,qBAAqB,CAAC;AAC5D,eAAO,MAAM,wBAAwB,2CAA2C,CAAC"}

package/executors/gateway/runtime/edge.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PREFLIGHT_METHODS_ROUTED = exports.PREFLIGHT_METHODS_NOROUTE = exports.corsPreflight = exports.cors = exports.GATEWAY_OWNED_HEADERS = exports.sendError = void 0;
+const gateway_errors_1 = require("../gateway-errors");
+/**
+ * Send a gateway-generated edge error as the JSON envelope `{ key, status, traceId, message? }` (NOT
+ * `text/plain`) + an `x-request-id` header — the SAME localized contract a service returns, so a browser
+ * app renders `t(key)` and surfaces the trace id. Mirrors the prod gateway's `sendError`.
+ */
+const sendError = (res, req, status, reason, detail) => {
+    const traceId = (0, gateway_errors_1.ensureRequestId)(req);
+    if (!res.headersSent)
+        res.writeHead(status, { 'content-type': gateway_errors_1.GATEWAY_ERROR_CONTENT_TYPE, 'x-request-id': traceId });
+    res.end((0, gateway_errors_1.gatewayErrorBody)(status, reason, traceId, detail));
+};
+exports.sendError = sendError;
+/**
+ * The gateway OWNS these headers — strip any client-supplied copy at ingress so identity + trust can
+ * only originate from the gateway (mirrors the prod gateway's stripTrust). Applied at the very top of
+ * BOTH the HTTP handler and the WS upgrade.
+ */
+exports.GATEWAY_OWNED_HEADERS = ['x-internal-token', 'x-api-key-id', 'x-user-id', 'x-tenant-id', 'x-user-roles', 'x-user-permissions'];
+/** Reflect the request Origin back with credentials — the gateway is the edge CORS authority. */
+const cors = (req, res) => {
+    const origin = String(req.headers.origin ?? '*');
+    res.setHeader('access-control-allow-origin', origin);
+    res.setHeader('access-control-allow-credentials', 'true');
+    res.setHeader('vary', 'Origin');
+};
+exports.cors = cors;
+/**
+ * Answer a CORS preflight (OPTIONS) at the edge: reflect CORS + 204 with the allowed `methods` and the
+ * requested headers echoed back. `methods` differs by caller — the no-route host-root uses the narrow
+ * `GET,HEAD,OPTIONS`; a routed path uses the wide verb list.
+ */
+const corsPreflight = (req, res, methods) => {
+    (0, exports.cors)(req, res);
+    res.writeHead(204, {
+        'access-control-allow-methods': methods,
+        'access-control-allow-headers': String(req.headers['access-control-request-headers'] ?? '*'),
+    });
+    res.end();
+};
+exports.corsPreflight = corsPreflight;
+/** Allowed-methods lists for the two preflight sites. */
+exports.PREFLIGHT_METHODS_NOROUTE = 'GET,HEAD,OPTIONS';
+exports.PREFLIGHT_METHODS_ROUTED = 'GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS';

package/executors/gateway/runtime/handler.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The HTTP request pipeline — the composition of every layer into one ordered
+ * flow. The ORDER here is a security contract (each step's position fixes a real
+ * bug); see the inline notes. Customer hooks slot in at the named phases.
+ *
+ *   strip-trust → onRequest → match → (no-route fallback) → routed-preflight →
+ *   cors → beforeAuth → auth/authz → afterAuth(+builtin middleware) →
+ *   inject-token → beforeForward → forward → onResponse / onError
+ */
+import type * as http from 'node:http';
+import type { GatewayRuntime } from './types';
+import type { Observability } from './observability';
+import type { EdgeAuth } from './auth';
+import type { ProxyLayer } from './proxy';
+import type { HooksLayer } from './hooks';
+export interface HandlerDeps {
+    rt: GatewayRuntime;
+    obs: Observability;
+    auth: EdgeAuth;
+    proxy: ProxyLayer;
+    hooks: HooksLayer;
+}
+export declare function createHandler(deps: HandlerDeps): http.RequestListener;
+//# sourceMappingURL=handler.d.ts.map

package/executors/gateway/runtime/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../../../../../libs/cluster/src/executors/gateway/runtime/handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,KAAK,IAAI,MAAM,WAAW,CAAC;AAWvC,OAAO,KAAK,EAAE,cAAc,EAAW,MAAM,SAAS,CAAC;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,cAAc,CAAC;IACnB,GAAG,EAAE,aAAa,CAAC;IACnB,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,UAAU,CAAC;IAClB,KAAK,EAAE,UAAU,CAAC;CACnB;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC,eAAe,CA2IrE"}

package/executors/gateway/runtime/handler.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHandler = createHandler;
+const manifest_1 = require("../manifest");
+const gateway_errors_1 = require("../gateway-errors");
+const discovery_1 = require("./discovery");
+const edge_1 = require("./edge");
+function createHandler(deps) {
+    const { rt, obs, auth, proxy, hooks } = deps;
+    const match = (req) => (0, manifest_1.matchRoute)(rt.routes, (req.headers.host || '').split(':')[0], req.url ?? '/');
+    // Host-root infra: when a host only has PATH-mounted services (pure
+    // microservices under api.<domain>/{prefix}), the gateway itself owns the
+    // root — CORS, health aggregation + service discovery, like a real edge.
+    const handleNoRoute = (req, res) => {
+        // gateway-owned endpoints are cross-origin by design (the app calls
+        // api.<domain>/health from app.<domain>) — answer CORS here; routed
+        // paths inherit CORS from the services themselves.
+        (0, edge_1.cors)(req, res);
+        if (req.method === 'OPTIONS') {
+            res.writeHead(204, {
+                'access-control-allow-methods': edge_1.PREFLIGHT_METHODS_NOROUTE,
+                'access-control-allow-headers': String(req.headers['access-control-request-headers'] ?? '*'),
+            });
+            res.end();
+            return;
+        }
+        const host = (req.headers.host || '').split(':')[0];
+        const mounted = rt.routes.filter((r) => r.host && (0, manifest_1.hostMatches)(r.host, host) && r.prefix);
+        const url = (req.url ?? '/').split('?')[0];
+        if (mounted.length > 0 && (url === '/health' || url === '/healthz')) {
+            const services = mounted.map((r) => ({
+                project: r.project,
+                prefix: r.prefix,
+                pods: r.pool ? ((0, discovery_1.pickSock)(r.pool, 0), r.pool.socks.length) : undefined,
+                state: r.svc?.state ?? (r.target ? 'up' : 'unknown'),
+            }));
+            const ok = services.every((s) => s.state !== 'down' || true);
+            res.writeHead(ok ? 200 : 503, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({ status: 'ok', host, services }, null, 2));
+            return;
+        }
+        if (mounted.length > 0 && url === '/.well-known/services') {
+            res.writeHead(200, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({ host, services: mounted.map((r) => ({ prefix: r.prefix, project: r.project, internal: !!r.internal })) }, null, 2));
+            return;
+        }
+        (0, edge_1.sendError)(res, req, 404, 'not_found', mounted.length > 0
+            ? `No service mounted at ${url}. Mounted on ${host}: ${[...new Set(mounted.map((r) => r.prefix))].join(', ')} (+ /health, /.well-known/services)`
+            : 'No gateway route for this hostname.');
+    };
+    const runPipeline = async (req, res) => {
+        // 1. STRIP client-supplied trust headers before anything else: the gateway is
+        // the ONLY party allowed to assert `x-internal-token` (came through me) and
+        // `x-api-key-id` (validated caller identity). Without this, a keyless/TCP route
+        // would leak a spoofed token and any public route would forward a spoofed caller
+        // id to downstream audit. The gateway re-stamps them below where earned.
+        for (const h of edge_1.GATEWAY_OWNED_HEADERS)
+            delete req.headers[h];
+        // 2. Mint a trace id for EVERY request (not just lens-traced ones): forwarded to the
+        // pod (adopted as its traceId) and returned on the response — any request is traceable.
+        (0, gateway_errors_1.ensureRequestId)(req);
+        const trace = obs.beginTrace(req);
+        if (trace) {
+            obs.traceStep(trace, 'received', { host: trace.host, method: trace.method, url: trace.url });
+            req.__lensmcpTrace = trace;
+        }
+        const ctx = hooks.httpContext(req, res, trace);
+        try {
+            // 3. onRequest (sees already-stripped headers; may short-circuit)
+            if (hooks.has('onRequest')) {
+                await hooks.run('onRequest', ctx);
+                if (ctx.responded())
+                    return;
+            }
+            // 4. route match
+            const route = match(req);
+            if (!route) {
+                handleNoRoute(req, res);
+                return;
+            }
+            ctx.route = route;
+            obs.traceStep(trace, 'route-match', {
+                project: route.project,
+                ...(route.prefix ? { prefix: route.prefix } : {}),
+                ...(route.host ? { routeHost: route.host } : {}),
+                ...(route.internal ? { internal: true } : {}),
+            });
+            // 7. CORS preflight on a ROUTED path: answer it HERE, BEFORE edge auth — an OPTIONS preflight
+            // carries no token by spec, so the JWT (or x-api-key) enforcement below would 401 it and the
+            // browser's CORS check fails. The matching real request still goes through auth normally.
+            if (req.method === 'OPTIONS') {
+                (0, edge_1.cors)(req, res);
+                res.writeHead(204, {
+                    'access-control-allow-methods': edge_1.PREFLIGHT_METHODS_ROUTED,
+                    'access-control-allow-headers': String(req.headers['access-control-request-headers'] ?? '*'),
+                });
+                res.end();
+                return;
+            }
+            // 8. CORS on EVERY routed response — including the 401/403/5xx the gateway generates ITSELF
+            // below. Without this a gateway-generated error short-circuits before the upstream (which
+            // carries CORS on success), so the browser sees the error WITHOUT an Access-Control-Allow-Origin
+            // and reports a CORS failure that MASKS the real status. On success the upstream's CORS header
+            // overwrites this one (http-proxy setHeader), so there's no duplicate.
+            (0, edge_1.cors)(req, res);
+            // 9. beforeAuth
+            if (hooks.has('beforeAuth')) {
+                await hooks.run('beforeAuth', ctx);
+                if (ctx.responded())
+                    return;
+            }
+            // 10/11. auth + authz. internal.* validates the caller's api-key; public verifies the end-user
+            // JWT + enforces per-route rules. Custom middleware (afterAuth) runs AFTER core auth, public ONLY.
+            if (route.internal) {
+                const v = auth.internal(req, route, trace);
+                if (!v.ok) {
+                    obs.finishTrace(trace, route.project, v.status);
+                    (0, edge_1.sendError)(res, req, v.status, v.reason, v.detail);
+                    return;
+                }
+                ctx.caller = v.caller;
+            }
+            else {
+                const v = auth.public(req, route, trace);
+                if (!v.ok) {
+                    obs.finishTrace(trace, route.project, v.status);
+                    (0, edge_1.sendError)(res, req, v.status, v.reason, v.detail);
+                    return;
+                }
+                ctx.claims = v.claims;
+                if (hooks.has('afterAuth')) {
+                    await hooks.run('afterAuth', ctx);
+                    if (ctx.responded())
+                        return;
+                }
+            }
+            // 12. inject the target service's key so pods trust the gateway (pool routes, both branches)
+            if (route.pool && rt.serviceKeys[route.project]) {
+                req.headers['x-internal-token'] = rt.serviceKeys[route.project];
+            }
+            // 13. beforeForward (last chance to mutate headers/url)
+            if (hooks.has('beforeForward')) {
+                await hooks.run('beforeForward', ctx);
+                if (ctx.responded())
+                    return;
+            }
+            // 15. onResponse — fire user handlers once the response closes (the built-in
+            // recordEdge/finishTrace live in proxy.forward's own close handler).
+            if (hooks.has('onResponse')) {
+                res.on('close', () => { ctx.status = res.statusCode ?? 0; void hooks.run('onResponse', ctx); });
+            }
+            // 14. forward
+            void proxy.forward(route, req, res);
+        }
+        catch (e) {
+            // A hook (or the pipeline) threw — narrate via onError, then 500 if nobody responded.
+            ctx.error = e;
+            if (hooks.has('onError'))
+                await hooks.run('onError', ctx);
+            if (!ctx.responded())
+                (0, edge_1.sendError)(res, req, 500, 'internal', e.message);
+        }
+    };
+    return (req, res) => { void runPipeline(req, res); };
+}

package/executors/gateway/runtime/hooks.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The customer extensibility layer: phase-named hooks. Customers register
+ * handlers per phase (`onRequest`, `beforeAuth`, `afterAuth`, `beforeForward`,
+ * `onResponse`, `onError`, `onUpgrade`); the built-in pipeline runs them in
+ * order at the matching point and short-circuits the moment one responds. The
+ * built-in `options.middleware` is wired (by the orchestrator) as the FIRST
+ * `afterAuth` handler, so "custom middleware runs AFTER core auth" is preserved.
+ */
+import type * as http from 'node:http';
+import type * as stream from 'node:stream';
+import type { GatewayHooks, GatewayPhase, GwTrace, HookContext } from './types';
+export interface HooksLayer {
+    /** Run every handler registered for `phase`, in order, stopping if one responds. */
+    run(phase: GatewayPhase, ctx: HookContext): Promise<void>;
+    /** True if any handler is registered for `phase` (lets the pipeline skip work). */
+    has(phase: GatewayPhase): boolean;
+    /** Build the per-request context for the HTTP pipeline. */
+    httpContext(req: http.IncomingMessage, res: http.ServerResponse, trace: GwTrace | undefined): HookContext;
+    /** Build the per-request context for the WS upgrade pipeline. */
+    upgradeContext(req: http.IncomingMessage, socket: stream.Duplex, trace: GwTrace | undefined): HookContext;
+}
+export declare function createHooks(hooks: GatewayHooks): HooksLayer;
+//# sourceMappingURL=hooks.d.ts.map

package/executors/gateway/runtime/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../../../../../libs/cluster/src/executors/gateway/runtime/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,KAAK,IAAI,MAAM,WAAW,CAAC;AACvC,OAAO,KAAK,KAAK,MAAM,MAAM,aAAa,CAAC;AAE3C,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAOhF,MAAM,WAAW,UAAU;IACzB,oFAAoF;IACpF,GAAG,CAAC,KAAK,EAAE,YAAY,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,mFAAmF;IACnF,GAAG,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC;IAClC,2DAA2D;IAC3D,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,EAAE,GAAG,EAAE,IAAI,CAAC,cAAc,EAAE,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,WAAW,CAAC;IAC1G,iEAAiE;IACjE,cAAc,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,WAAW,CAAC;CAC3G;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,YAAY,GAAG,UAAU,CA6C3D"}

package/executors/gateway/runtime/hooks.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHooks = createHooks;
+const edge_1 = require("./edge");
+// Terminal phases observe a request whose response is ALREADY complete, so
+// `responded()` is true by definition — they must run every handler regardless.
+// The request-flow phases short-circuit the moment a handler responds.
+const TERMINAL_PHASES = new Set(['onResponse', 'onError']);
+function createHooks(hooks) {
+    const run = async (phase, ctx) => {
+        const list = hooks[phase];
+        if (!list || list.length === 0)
+            return;
+        const terminal = TERMINAL_PHASES.has(phase);
+        for (const h of list) {
+            if (!terminal && ctx.responded())
+                return; // a request-flow hook already responded → stop
+            await h(ctx);
+        }
+    };
+    const has = (phase) => (hooks[phase]?.length ?? 0) > 0;
+    const httpContext = (req, res, trace) => ({
+        req,
+        res,
+        socket: undefined,
+        trace,
+        route: undefined,
+        claims: undefined,
+        caller: undefined,
+        pod: undefined,
+        error: undefined,
+        status: undefined,
+        sendError: (status, reason, detail) => (0, edge_1.sendError)(res, req, status, reason, detail),
+        responded: () => res.writableEnded || res.headersSent,
+    });
+    const upgradeContext = (req, socket, trace) => ({
+        req,
+        res: undefined,
+        socket,
+        trace,
+        route: undefined,
+        claims: undefined,
+        caller: undefined,
+        pod: undefined,
+        error: undefined,
+        status: undefined,
+        // No HTTP response on an upgrade — short-circuiting means destroying the socket.
+        sendError: () => { try {
+            socket.destroy();
+        }
+        catch { /* already gone */ } },
+        responded: () => socket.destroyed,
+    });
+    return { run, has, httpContext, upgradeContext };
+}

package/executors/gateway/runtime/lens-children.d.ts

@@ -0,0 +1,13 @@
+import { type SpawnChild } from '@lensmcp/nx-plugin/lens-frontend';
+import type { GatewayRuntime, GatewayRuntimeOptions } from './types';
+import type { Observability } from './observability';
+export interface LensChildren {
+    spawnManagedChild: SpawnChild;
+    /** Boot the dashboard + MCP singletons and every `lens:true` app. Pushes the
+     *  dashboard route onto `rt.routes` — MUST run before TLS SAN derivation. */
+    bootSingletonsAndApps(): void;
+    /** Reap all managed children (called from `stop()`). */
+    reapAll(): void;
+}
+export declare function createLensChildren(rt: GatewayRuntime, obs: Observability, options: GatewayRuntimeOptions): LensChildren;
+//# sourceMappingURL=lens-children.d.ts.map

package/executors/gateway/runtime/lens-children.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lens-children.d.ts","sourceRoot":"","sources":["../../../../../../libs/cluster/src/executors/gateway/runtime/lens-children.ts"],"names":[],"mappings":"AAQA,OAAO,EAIL,KAAK,UAAU,EAChB,MAAM,kCAAkC,CAAC;AAE1C,OAAO,KAAK,EAAE,cAAc,EAAE,qBAAqB,EAAgB,MAAM,SAAS,CAAC;AACnF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAMrD,MAAM,WAAW,YAAY;IAC3B,iBAAiB,EAAE,UAAU,CAAC;IAC9B;iFAC6E;IAC7E,qBAAqB,IAAI,IAAI,CAAC;IAC9B,wDAAwD;IACxD,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,cAAc,EAAE,GAAG,EAAE,aAAa,EAAE,OAAO,EAAE,qBAAqB,GAAG,YAAY,CA0HvH"}