@daloyjs/core 0.36.0 → 0.37.0

package/dist/mtls.d.ts

@@ -0,0 +1,266 @@
+/**
+ * Mutual-TLS / client-certificate authentication.
+ *
+ * The Web-standard {@link Request} does not surface the TLS peer certificate,
+ * so — exactly like {@link "./conn-info.js"} does for the peer IP — adapters
+ * (or a trusted TLS-terminating reverse proxy) attach a normalized
+ * {@link ClientCertificate} to the request, and the {@link clientCertAuth}
+ * middleware reads it back to enforce a client-certificate identity for
+ * zero-trust / service-to-service deployments.
+ *
+ * Two population paths are supported, both runtime-portable and dependency-free:
+ *
+ * 1. **Native TLS** — when the runtime terminates TLS itself (the Node adapter
+ *    reads `tls.TLSSocket#getPeerCertificate()`), the adapter stashes a lazy
+ *    thunk via {@link setClientCertificate}; the certificate is only normalized
+ *    if a `clientCertAuth()`-guarded route actually reads it, so plain requests
+ *    pay nothing.
+ * 2. **Forwarded by a trusted proxy** — when TLS is terminated upstream
+ *    (Envoy, nginx, HAProxy, Traefik, a cloud load balancer), the proxy forwards
+ *    the verified client identity in request headers. {@link clientCertAuth}
+ *    can parse Envoy's `X-Forwarded-Client-Cert` (XFCC) or a set of operator-named
+ *    structured headers (nginx `$ssl_client_*`, etc.). Because those headers are
+ *    spoofable by anything that can reach the app directly, the header path is
+ *    opt-in and must be paired with a `behindProxy` posture that guarantees the
+ *    app is only reachable through the terminating proxy.
+ *
+ * @module
+ * @since 0.37.0
+ */
+import type { BaseContext, Hooks } from "./types.js";
+/**
+ * Normalized view of a TLS client certificate, independent of how it was
+ * obtained (native socket vs. forwarded proxy header). Every field except
+ * {@link subjectAltNames} and {@link verified} is optional because different
+ * sources expose different subsets.
+ *
+ * @since 0.37.0
+ */
+export interface ClientCertificate {
+    /** Full subject distinguished name, e.g. `"CN=svc-a,OU=payments,O=acme"`. */
+    readonly subjectDN?: string;
+    /** Subject common name (the `CN=` RDN), if present. */
+    readonly subjectCN?: string;
+    /** Full issuer distinguished name. */
+    readonly issuerDN?: string;
+    /** Issuer common name (the `CN=` RDN), if present. */
+    readonly issuerCN?: string;
+    /** Certificate serial number (hex string), if known. */
+    readonly serialNumber?: string;
+    /**
+     * SHA-256 fingerprint. Normalized to uppercase hex **without** separators
+     * (colons stripped) so allow-list comparison is source-independent.
+     */
+    readonly fingerprint256?: string;
+    /**
+     * Subject Alternative Names as `TYPE:value` entries (e.g. `"DNS:svc-a.internal"`,
+     * `"URI:spiffe://acme/svc-a"`, `"IP:10.0.0.7"`). Empty array when none.
+     */
+    readonly subjectAltNames: readonly string[];
+    /** `notBefore` validity bound, if the source exposed it. */
+    readonly notBefore?: Date;
+    /** `notAfter` validity bound, if the source exposed it. */
+    readonly notAfter?: Date;
+    /**
+     * Whether the TLS terminator **cryptographically verified** the certificate
+     * chain. `clientCertAuth({ requireVerified: true })` (the default) refuses
+     * any certificate where this is `false`.
+     */
+    readonly verified: boolean;
+    /** PEM text, when the source forwarded it (XFCC `Cert=`). */
+    readonly pem?: string;
+}
+/**
+ * A {@link ClientCertificate} or a lazy thunk that produces one. Adapters stash
+ * a thunk so the (potentially expensive) certificate read only happens if a
+ * guarded route actually inspects it.
+ *
+ * @since 0.37.0
+ */
+export type ClientCertificateSource = ClientCertificate | undefined | (() => ClientCertificate | undefined);
+/**
+ * @internal Adapter helper — attach a {@link ClientCertificate} (or a lazy
+ * thunk producing one) to a `Request`. Mirrors {@link "./conn-info.js".setConnInfo}.
+ * Pass a thunk to defer the read until {@link getClientCertificate} is first
+ * called; the resolved value is cached back onto the request.
+ *
+ * @since 0.37.0
+ */
+export declare function setClientCertificate(request: Request, source: ClientCertificateSource): void;
+/**
+ * Read the {@link ClientCertificate} an adapter attached to this request, or
+ * `undefined` when the connection presented no client certificate (or the
+ * adapter does not expose TLS peer info). If a lazy thunk was stashed, it is
+ * resolved once and the result cached.
+ *
+ * @since 0.37.0
+ */
+export declare function getClientCertificate(request: Request): ClientCertificate | undefined;
+/**
+ * Shape of the object returned by Node's `tls.TLSSocket#getPeerCertificate(true)`.
+ * Declared structurally so {@link normalizePeerCertificate} stays dependency-free
+ * and importable in non-Node runtimes.
+ *
+ * @since 0.37.0
+ */
+export interface PeerCertificateLike {
+    subject?: Record<string, string | string[]> | null;
+    issuer?: Record<string, string | string[]> | null;
+    valid_from?: string;
+    valid_to?: string;
+    fingerprint256?: string;
+    serialNumber?: string;
+    subjectaltname?: string;
+}
+/**
+ * Normalize a Node `getPeerCertificate(true)` result into a
+ * {@link ClientCertificate}. Returns `undefined` for the empty object Node
+ * returns when the peer presented no certificate.
+ *
+ * @param raw - The structured peer-certificate object from the TLS socket.
+ * @param verified - Whether the socket reported `authorized === true` (the
+ *   chain was verified against the configured CA).
+ * @since 0.37.0
+ */
+export declare function normalizePeerCertificate(raw: PeerCertificateLike | null | undefined, verified: boolean): ClientCertificate | undefined;
+/**
+ * Parse an Envoy `X-Forwarded-Client-Cert` (XFCC) header value into a
+ * {@link ClientCertificate}. XFCC is a comma-separated list of proxy elements,
+ * each a `;`-delimited set of `Key=Value` pairs (`Hash`, `Subject`, `URI`,
+ * `DNS`, `Cert`, …). The **first** element is the client closest to the origin
+ * and is the one returned. Because Envoy only emits XFCC for connections it
+ * mutually authenticated, the result is marked `verified: true`.
+ *
+ * Returns `undefined` for an empty or unparseable header.
+ *
+ * @since 0.37.0
+ */
+export declare function parseForwardedClientCert(headerValue: string | null | undefined): ClientCertificate | undefined;
+/**
+ * Configuration for reading a forwarded client certificate out of request
+ * headers set by a trusted TLS-terminating proxy.
+ *
+ * @since 0.37.0
+ */
+export type ClientCertHeaderConfig = {
+    /** Envoy `X-Forwarded-Client-Cert` format. */
+    readonly format: "xfcc";
+    /** Header name. Default: `"x-forwarded-client-cert"`. */
+    readonly name?: string;
+} | {
+    /**
+     * Operator-named structured headers (nginx `$ssl_client_*`, HAProxy,
+     * Traefik). Each property is the header name carrying that field.
+     */
+    readonly format: "structured";
+    /** Header carrying the subject DN (e.g. nginx `$ssl_client_s_dn`). */
+    readonly subjectDN?: string;
+    /** Header carrying the issuer DN (e.g. nginx `$ssl_client_i_dn`). */
+    readonly issuerDN?: string;
+    /** Header carrying the SHA-256 fingerprint (e.g. nginx `$ssl_client_fingerprint`). */
+    readonly fingerprint?: string;
+    /** Header carrying the serial number. */
+    readonly serialNumber?: string;
+    /** Header carrying a comma-separated SAN list. */
+    readonly san?: string;
+    /** Header carrying the verification result (e.g. nginx `$ssl_client_verify`). */
+    readonly verify?: string;
+    /**
+     * Value of the `verify` header that means "chain verified". Default:
+     * `"SUCCESS"` (nginx). Compared case-insensitively.
+     */
+    readonly verifySuccessValue?: string;
+};
+/**
+ * Options for {@link clientCertAuth}.
+ *
+ * @since 0.37.0
+ */
+export interface ClientCertAuthOptions {
+    /**
+     * Override how the certificate is sourced. Defaults to reading whatever the
+     * adapter attached via {@link setClientCertificate} (native TLS), falling
+     * back to {@link header} parsing when configured.
+     */
+    resolve?: (ctx: BaseContext<any, any>) => ClientCertificate | undefined;
+    /**
+     * Read the certificate from a trusted-proxy header instead of (or in
+     * addition to) the native adapter source. **Spoofable** unless the app is
+     * only reachable through the terminating proxy — pair with a strict
+     * `behindProxy` posture.
+     */
+    header?: ClientCertHeaderConfig;
+    /**
+     * Require the TLS terminator to have cryptographically verified the chain
+     * (`cert.verified === true`). Default: `true`. Only disable when an upstream
+     * component performs verification out of band.
+     */
+    requireVerified?: boolean;
+    /** If set, the subject CN must exactly match one of these values. */
+    allowSubjectCNs?: readonly string[];
+    /** If set, the issuer CN must exactly match one of these values. */
+    allowIssuerCNs?: readonly string[];
+    /**
+     * If set, the certificate's SHA-256 fingerprint must match one of these
+     * (compared in constant time; colons/spaces and case are ignored).
+     */
+    allowFingerprints?: readonly string[];
+    /**
+     * If set, at least one Subject Alternative Name must match one of these.
+     * Entries may be given as `TYPE:value` (e.g. `"URI:spiffe://acme/svc-a"`) or
+     * as a bare value matched against any SAN's value part.
+     */
+    allowSANs?: readonly string[];
+    /**
+     * Reject certificates outside their `[notBefore, notAfter]` validity window
+     * when those bounds are known. Default: `true`. (A verifying TLS terminator
+     * already enforces this, but a header-forwarded cert may not have been
+     * fully validated.)
+     */
+    checkValidity?: boolean;
+    /**
+     * Custom per-request check, run after all built-in checks pass. Returning
+     * `false` rejects with `403`; `true`/`undefined` accepts.
+     */
+    verify?: (cert: ClientCertificate, ctx: BaseContext<any, any>) => boolean | void | Promise<boolean | void>;
+    /** Rejection message for the `403` responses. Default: `"Client certificate not permitted"`. */
+    message?: string;
+    /** `ctx.state` key the accepted certificate is stamped on. Default: `"clientCertificate"`. */
+    stateKey?: string;
+    /** @internal Injectable clock for validity-window tests. */
+    now?: () => number;
+}
+/**
+ * Middleware enforcing mutual-TLS client-certificate authentication. Reads the
+ * normalized {@link ClientCertificate} attached by the adapter (native TLS) or
+ * parsed from a trusted-proxy header, enforces verification + optional
+ * allow-lists + validity window + a custom hook, and stamps the accepted
+ * certificate on `ctx.state` for downstream handlers.
+ *
+ * Rejection semantics:
+ * - **No certificate presented** → `401` `application/problem+json` with
+ *   `Cache-Control: no-store`.
+ * - **Unverified / not allow-listed / expired / custom-rejected** → `403`
+ *   {@link ForbiddenError} (never echoes certificate details).
+ *
+ * @example Native TLS (Node adapter terminates mTLS):
+ * ```ts
+ * app.use(clientCertAuth({
+ *   allowIssuerCNs: ["acme-internal-ca"],
+ *   allowSANs: ["URI:spiffe://acme/svc-a"],
+ * }));
+ * ```
+ *
+ * @example Behind an Envoy proxy forwarding XFCC:
+ * ```ts
+ * app.use(clientCertAuth({
+ *   header: { format: "xfcc" },
+ *   allowFingerprints: [process.env.PEER_FINGERPRINT!],
+ * }));
+ * ```
+ *
+ * @param opts - Verification, allow-list, header-source, and hook options.
+ * @returns A {@link Hooks} bundle for `app.use(...)`.
+ * @since 0.37.0
+ */
+export declare function clientCertAuth(opts?: ClientCertAuthOptions): Hooks;