@pristine-ts/http 4.0.2 → 4.0.3

package/dist/types/cors/cors-preflight-response.interface.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The answer `CorsRequestHandler` produces for a CORS preflight that must be short-circuited
+ * before routing. `KernelHttpServer` writes `statusCode` and `headers` straight to the
+ * `ServerResponse` without ever invoking `kernel.handle()` — a preflight never corresponds to a
+ * real route.
+ */
+export interface CorsPreflightResponseInterface {
+    /**
+     * The status code to write. Always `204 No Content` for a preflight.
+     */
+    statusCode: number;
+    /**
+     * The response headers to write. Populated with the `Access-Control-*` set when the origin is
+     * allow-listed; an empty object when it is not (the browser then blocks for lack of an
+     * `Access-Control-Allow-Origin`, and we never reflect an arbitrary origin or emit `"*"`).
+     */
+    headers: {
+        [name: string]: string;
+    };
+}

package/dist/types/cors/cors-request-context.interface.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The normalized, transport-agnostic view of a request that `CorsRequestHandler` needs to make
+ * a CORS decision. Extracted from Node's `IncomingMessage` (via `CorsRequestHandler.buildContext`)
+ * so the decision logic can be unit-tested without a live socket or a Node request object.
+ */
+export interface CorsRequestContextInterface {
+    /**
+     * The upper-cased HTTP method (e.g. `"GET"`, `"OPTIONS"`).
+     */
+    method: string;
+    /**
+     * The `Origin` request header, if present. Absent for same-origin and non-browser callers.
+     */
+    origin?: string;
+    /**
+     * The `Host` request header, if present. Compared against the `allowed-hosts` allowlist as a
+     * DNS-rebinding defense for loopback servers.
+     */
+    host?: string;
+    /**
+     * The `Access-Control-Request-Method` preflight header. Its presence on an `OPTIONS` request
+     * is what distinguishes a CORS preflight from an ordinary `OPTIONS`.
+     */
+    accessControlRequestMethod?: string;
+    /**
+     * The `Access-Control-Request-Headers` preflight header, listing the headers the actual
+     * request intends to send.
+     */
+    accessControlRequestHeaders?: string;
+    /**
+     * `true` when the request carried `Access-Control-Request-Private-Network: true` — the Chrome
+     * Private Network Access preflight signal emitted when a public/secure context targets a more
+     * private address space (e.g. a loopback daemon).
+     */
+    accessControlRequestPrivateNetwork: boolean;
+}

package/dist/types/cors/cors-request.handler.d.ts

@@ -0,0 +1,94 @@
+import { CorsRequestContextInterface } from "./cors-request-context.interface";
+import { CorsPreflightResponseInterface } from "./cors-preflight-response.interface";
+/**
+ * The config-driven CORS policy engine that `KernelHttpServer` consults inside its request path,
+ * BEFORE `kernel.handle()` — the one place that sees the raw request/response and can answer a
+ * preflight or reject an origin without the networking `Router` ever running.
+ *
+ * All decision methods are pure functions of the injected configuration plus a normalized
+ * {@link CorsRequestContextInterface}, so the full behavior matrix is unit-testable by
+ * constructing this class directly (no live socket, no Node request object required).
+ *
+ * ## Activation
+ * CORS is **inactive unless configured**. Two independent switches:
+ *   - `cors.allowed-origins` non-empty  → origin/preflight/header-echo logic activates.
+ *   - `cors.allowed-hosts`   non-empty  → the Host-header allowlist (DNS-rebinding defense) activates.
+ * With neither set, every method is a no-op and the server behaves exactly as it did before CORS
+ * existed.
+ *
+ * ## Guarantees
+ *   - Never emits `Access-Control-Allow-Origin: *` — only an exact echo of an allow-listed Origin.
+ *   - Never reflects an arbitrary Origin — an Origin absent from the allowlist gets no ACAO headers.
+ */
+export declare class CorsRequestHandler {
+    private readonly allowedOrigins;
+    private readonly allowedMethods;
+    private readonly allowedHeaders;
+    private readonly exposedHeaders;
+    private readonly maxAge;
+    private readonly allowCredentials;
+    private readonly allowPrivateNetwork;
+    private readonly allowedHosts;
+    constructor(allowedOrigins: string | string[], allowedMethods: string | string[], allowedHeaders: string | string[], exposedHeaders: string | string[], maxAge: number, allowCredentials: boolean, allowPrivateNetwork: boolean, allowedHosts: string | string[]);
+    /**
+     * `true` when an origin allowlist is configured — gates the preflight short-circuit and the
+     * `Access-Control-Allow-Origin` echo on actual responses.
+     */
+    get isOriginCheckEnabled(): boolean;
+    /**
+     * `true` when a Host allowlist is configured — gates the DNS-rebinding 403.
+     */
+    get isHostCheckEnabled(): boolean;
+    /**
+     * Whether any CORS feature is active. `KernelHttpServer` can skip all CORS work when this is
+     * `false`, keeping the un-configured request path byte-for-byte identical to before.
+     */
+    get isEnabled(): boolean;
+    /**
+     * Normalizes a raw Node request into the transport-agnostic {@link CorsRequestContextInterface}.
+     * Node lower-cases header names on `IncomingMessage`, and multi-valued headers arrive as arrays;
+     * we take the method + the CORS-relevant headers and coerce them to the single-string shape the
+     * decision methods expect.
+     */
+    buildContext(method: string, headers: {
+        [key: string]: string | string[] | undefined;
+    }): CorsRequestContextInterface;
+    /**
+     * Host-header allowlist check (loopback DNS-rebinding defense). Returns `true` (allow) when no
+     * allowlist is configured; otherwise the request's `Host` must exactly match a configured entry
+     * (case-insensitive, since host names are). A missing `Host` against a configured allowlist is
+     * rejected. `KernelHttpServer` turns a `false` here into a `403` before any routing.
+     */
+    isHostAllowed(host: string | undefined): boolean;
+    /**
+     * Exact-match origin allowlist check. An absent Origin is never "allowed" (there is nothing to
+     * echo). We never wildcard and never reflect an arbitrary Origin.
+     */
+    isOriginAllowed(origin: string | undefined): boolean;
+    /**
+     * Decides whether `context` is a CORS preflight that must be answered before routing, and if so
+     * returns the `204` response (status + headers) to write. Returns `undefined` when the request is
+     * not a preflight we own — the caller then lets it route normally.
+     *
+     * A CORS preflight is an `OPTIONS` carrying `Access-Control-Request-Method`. We only take over
+     * preflight handling when an origin allowlist is configured (same-origin requests never send
+     * `Access-Control-Request-Method`, so app-owned `OPTIONS` routes are never stolen). An allow-listed
+     * Origin gets the full `Access-Control-*` set; a disallowed Origin still gets a bare `204` with no
+     * ACAO — the browser blocks it, and we never leak an arbitrary Origin.
+     */
+    buildPreflightResponse(context: CorsRequestContextInterface): CorsPreflightResponseInterface | undefined;
+    /**
+     * The CORS headers to add to an ACTUAL (non-preflight) response — success OR error. Returns an
+     * empty object when origin-checking is off or the Origin is not allow-listed. Applied to 4xx/5xx
+     * responses too: without `Access-Control-Allow-Origin` the browser cannot read an error body.
+     */
+    buildResponseHeaders(origin: string | undefined): {
+        [name: string]: string;
+    };
+    /**
+     * Coerces a list-shaped config value into a trimmed, empty-stripped `string[]`. Accepts both the
+     * comma-separated string form (env vars / defaults) and the `string[]` form (programmatic
+     * `kernel.start()` config).
+     */
+    private normalizeList;
+}

package/dist/types/cors/cors.d.ts

@@ -0,0 +1,3 @@
+export * from "./cors-preflight-response.interface";
+export * from "./cors-request-context.interface";
+export * from "./cors-request.handler";

package/dist/types/http.configuration-keys.d.ts

@@ -17,6 +17,20 @@ export declare const HttpConfigurationKeys: {
     readonly KernelServerPort: "pristine.http.kernel-server.port";
     readonly KernelServerTlsKeyPath: "pristine.http.kernel-server.tls.key-path";
     readonly KernelServerTlsCertPath: "pristine.http.kernel-server.tls.cert-path";
+    /**
+     * CORS keys consumed by `CorsRequestHandler` inside `KernelHttpServer`'s request path.
+     * CORS is inactive unless `cors.allowed-origins` (and/or `cors.allowed-hosts`) is set —
+     * a server with none of these configured behaves exactly as it did before CORS existed.
+     * Each list key accepts a comma-separated string or a `string[]`.
+     */
+    readonly CorsAllowedOrigins: "pristine.http.cors.allowed-origins";
+    readonly CorsAllowedMethods: "pristine.http.cors.allowed-methods";
+    readonly CorsAllowedHeaders: "pristine.http.cors.allowed-headers";
+    readonly CorsExposedHeaders: "pristine.http.cors.exposed-headers";
+    readonly CorsMaxAge: "pristine.http.cors.max-age";
+    readonly CorsAllowCredentials: "pristine.http.cors.allow-credentials";
+    readonly CorsAllowPrivateNetwork: "pristine.http.cors.allow-private-network";
+    readonly CorsAllowedHosts: "pristine.http.cors.allowed-hosts";
 };
 /**
  * The expected runtime types for each configuration value defined by `@pristine-ts/http`.
@@ -30,6 +44,14 @@ export interface HttpConfigurationValueMap {
     "pristine.http.kernel-server.port": number;
     "pristine.http.kernel-server.tls.key-path": string;
     "pristine.http.kernel-server.tls.cert-path": string;
+    "pristine.http.cors.allowed-origins": string;
+    "pristine.http.cors.allowed-methods": string;
+    "pristine.http.cors.allowed-headers": string;
+    "pristine.http.cors.exposed-headers": string;
+    "pristine.http.cors.max-age": number;
+    "pristine.http.cors.allow-credentials": boolean;
+    "pristine.http.cors.allow-private-network": boolean;
+    "pristine.http.cors.allowed-hosts": string;
 }
 /**
  * Augments the global `PristineConfigurationValueMap` (defined in `@pristine-ts/common`)

package/dist/types/http.module.d.ts

@@ -2,6 +2,7 @@ import { ModuleInterface } from "@pristine-ts/common";
 export * from "./http.module.keyname";
 export * from "./commands/commands";
 export * from "./clients/clients";
+export * from "./cors/cors";
 export * from "./enums/enums";
 export * from "./errors/errors";
 export * from "./interceptors/interceptors";

package/dist/types/servers/kernel.http-server.d.ts

@@ -1,5 +1,6 @@
 import { EventIdManager, Kernel, RuntimeServerInterface } from "@pristine-ts/core";
 import { LogHandlerInterface } from "@pristine-ts/logging";
+import { CorsRequestHandler } from "../cors/cors-request.handler";
 /**
  * Per-request override of the start-time bound port/address pair. Both are optional — when
  * absent, the server falls back to the values resolved from `pristine.http.kernel-server.*`
@@ -37,6 +38,7 @@ export declare class KernelHttpServer implements RuntimeServerInterface {
     private readonly logHandler;
     private readonly kernel;
     private readonly eventIdManager;
+    private readonly corsRequestHandler;
     /**
      * Identifier reported back via `RuntimeServerInterface.name`. Switches to `"https"` when
      * TLS config is present, mainly so log lines and `pristine info`-style introspection make
@@ -54,7 +56,7 @@ export declare class KernelHttpServer implements RuntimeServerInterface {
      * @private
      */
     private readonly connections;
-    constructor(defaultAddress: string, defaultPort: number, defaultTlsKeyPath: string, defaultTlsCertPath: string, logHandler: LogHandlerInterface, kernel: Kernel, eventIdManager: EventIdManager);
+    constructor(defaultAddress: string, defaultPort: number, defaultTlsKeyPath: string, defaultTlsCertPath: string, logHandler: LogHandlerInterface, kernel: Kernel, eventIdManager: EventIdManager, corsRequestHandler: CorsRequestHandler);
     /**
      * Binds the server. Resolves once the underlying server is listening; rejects on bind error
      * (port in use, EACCES, etc).
@@ -71,6 +73,12 @@ export declare class KernelHttpServer implements RuntimeServerInterface {
     stop(options?: {
         drainTimeoutMs?: number;
     }): Promise<void>;
+    /**
+     * The address the underlying server is bound to, or `null` when not listening. For a TCP socket
+     * this is `{address, family, port}` — useful when binding to port `0` (ephemeral port) and the
+     * caller needs to discover the assigned port afterwards.
+     */
+    getAddress(): import("net").AddressInfo | string | null;
     /**
      * Reads the body, builds a Pristine `Request`, dispatches via the kernel, writes the
      * resulting `Response`. All errors are caught and turned into a 500 response so the
@@ -97,6 +105,10 @@ export declare class KernelHttpServer implements RuntimeServerInterface {
      * Writes a Pristine `Response` (or any object — handlers that return raw JSON serialize as-is)
      * back to the underlying `ServerResponse`. Default status is 200, default content-type is
      * `application/json` when the body is non-string.
+     *
+     * `corsHeaders` (empty when CORS is off or the Origin isn't allow-listed) is applied AFTER the
+     * response's own headers so the `Access-Control-*` set is authoritative and a handler can't
+     * accidentally clobber it.
      * @private
      */
     private writeResponse;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pristine-ts/http",
-  "version": "4.0.2",
+  "version": "4.0.3",
   "description": "",
   "module": "dist/lib/esm/http.module.js",
   "main": "dist/lib/cjs/http.module.js",
@@ -16,14 +16,14 @@
   ],
   "dependencies": {
     "@pristine-ts/class-validator": "^2.0.4",
-    "@pristine-ts/cli": "^4.0.2",
-    "@pristine-ts/common": "^4.0.2",
-    "@pristine-ts/configuration": "^4.0.2",
-    "@pristine-ts/core": "^4.0.2",
-    "@pristine-ts/data-mapping": "^4.0.2",
-    "@pristine-ts/logging": "^4.0.2",
-    "@pristine-ts/observability": "^4.0.2",
-    "@pristine-ts/validation": "^4.0.2",
+    "@pristine-ts/cli": "^4.0.3",
+    "@pristine-ts/common": "^4.0.3",
+    "@pristine-ts/configuration": "^4.0.3",
+    "@pristine-ts/core": "^4.0.3",
+    "@pristine-ts/data-mapping": "^4.0.3",
+    "@pristine-ts/logging": "^4.0.3",
+    "@pristine-ts/observability": "^4.0.3",
+    "@pristine-ts/validation": "^4.0.3",
     "tsyringe": "^4.8.0"
   },
   "author": "",
@@ -65,7 +65,7 @@
       "src/*.{js,ts}"
     ]
   },
-  "gitHead": "ff1d17406b92dc73891b7091840c72dcfe84aea6",
+  "gitHead": "c301b556f877d7d16e6e5e8faf049c9e3b99e15a",
   "repository": {
     "type": "git",
     "url": "https://github.com/magieno/pristine-ts.git",