@daloyjs/core 0.36.0 → 0.38.0

package/dist/mtls.js

@@ -0,0 +1,488 @@
+/**
+ * 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 { ForbiddenError } from "./errors.js";
+import { timingSafeEqual } from "./security.js";
+const CLIENT_CERT_SYMBOL = Symbol.for("daloyjs.clientCertificate");
+/**
+ * @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 function setClientCertificate(request, source) {
+    request[CLIENT_CERT_SYMBOL] = source;
+}
+/**
+ * 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 function getClientCertificate(request) {
+    const store = request;
+    const source = store[CLIENT_CERT_SYMBOL];
+    if (typeof source === "function") {
+        const resolved = source();
+        store[CLIENT_CERT_SYMBOL] = resolved;
+        return resolved;
+    }
+    return source;
+}
+/**
+ * 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 function normalizePeerCertificate(raw, verified) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const subjectDN = dnFromRecord(raw.subject);
+    const issuerDN = dnFromRecord(raw.issuer);
+    const hasAnyField = subjectDN !== undefined ||
+        issuerDN !== undefined ||
+        raw.fingerprint256 !== undefined ||
+        raw.serialNumber !== undefined;
+    if (!hasAnyField)
+        return undefined;
+    return {
+        subjectDN,
+        subjectCN: cnFromRecord(raw.subject),
+        issuerDN,
+        issuerCN: cnFromRecord(raw.issuer),
+        serialNumber: raw.serialNumber,
+        fingerprint256: normalizeFingerprint(raw.fingerprint256),
+        subjectAltNames: parseNodeSubjectAltName(raw.subjectaltname),
+        notBefore: parseCertDate(raw.valid_from),
+        notAfter: parseCertDate(raw.valid_to),
+        verified,
+    };
+}
+function dnFromRecord(rec) {
+    if (!rec || typeof rec !== "object")
+        return undefined;
+    const parts = [];
+    for (const key of Object.keys(rec)) {
+        const value = rec[key];
+        if (Array.isArray(value)) {
+            for (const v of value)
+                parts.push(`${key}=${v}`);
+        }
+        else if (value !== undefined) {
+            parts.push(`${key}=${value}`);
+        }
+    }
+    return parts.length > 0 ? parts.join(",") : undefined;
+}
+function cnFromRecord(rec) {
+    if (!rec || typeof rec !== "object")
+        return undefined;
+    const cn = rec["CN"];
+    if (Array.isArray(cn))
+        return cn[0];
+    return cn;
+}
+function normalizeFingerprint(fp) {
+    if (typeof fp !== "string" || fp.length === 0)
+        return undefined;
+    // Strip colon separators and uppercase so XFCC `Hash=` (no separators) and
+    // Node `fingerprint256` (colon-delimited) compare identically.
+    let out = "";
+    for (let i = 0; i < fp.length; i++) {
+        const c = fp.charCodeAt(i);
+        if (c === 58 /* ':' */ || c === 32 /* space */)
+            continue;
+        out += fp[i];
+    }
+    return out.toUpperCase();
+}
+function parseCertDate(value) {
+    if (typeof value !== "string" || value.length === 0)
+        return undefined;
+    const ms = Date.parse(value);
+    return Number.isNaN(ms) ? undefined : new Date(ms);
+}
+function parseNodeSubjectAltName(san) {
+    if (typeof san !== "string" || san.length === 0)
+        return [];
+    // Node renders SANs as `DNS:a, IP Address:1.2.3.4, URI:spiffe://...`.
+    const out = [];
+    for (const piece of san.split(",")) {
+        const trimmed = piece.trim();
+        if (trimmed.length === 0)
+            continue;
+        out.push(trimmed.replace(/^IP Address:/i, "IP:"));
+    }
+    return out;
+}
+/**
+ * Split a string on a single-character separator while ignoring separators that
+ * appear inside double-quoted spans. No backtracking — single linear scan.
+ *
+ * @internal
+ */
+function splitRespectingQuotes(value, sep) {
+    const out = [];
+    let current = "";
+    let inQuotes = false;
+    for (let i = 0; i < value.length; i++) {
+        const ch = value[i];
+        if (ch === '"') {
+            inQuotes = !inQuotes;
+            current += ch;
+        }
+        else if (ch === sep && !inQuotes) {
+            out.push(current);
+            current = "";
+        }
+        else {
+            current += ch;
+        }
+    }
+    out.push(current);
+    return out;
+}
+function unquote(value) {
+    const trimmed = value.trim();
+    if (trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+}
+function cnFromDN(dn) {
+    if (!dn)
+        return undefined;
+    for (const rdn of splitRespectingQuotes(dn, ",")) {
+        const eq = rdn.indexOf("=");
+        if (eq === -1)
+            continue;
+        const key = rdn.slice(0, eq).trim();
+        if (key.toUpperCase() === "CN")
+            return unquote(rdn.slice(eq + 1));
+    }
+    return 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 function parseForwardedClientCert(headerValue) {
+    if (typeof headerValue !== "string" || headerValue.trim().length === 0) {
+        return undefined;
+    }
+    const firstElement = splitRespectingQuotes(headerValue, ",")[0];
+    if (!firstElement || firstElement.trim().length === 0)
+        return undefined;
+    let subjectDN;
+    let fingerprint256;
+    let serialNumber;
+    let pem;
+    const sans = [];
+    for (const pair of splitRespectingQuotes(firstElement, ";")) {
+        const eq = pair.indexOf("=");
+        if (eq === -1)
+            continue;
+        const key = pair.slice(0, eq).trim().toLowerCase();
+        const value = unquote(pair.slice(eq + 1));
+        if (value.length === 0)
+            continue;
+        switch (key) {
+            case "subject":
+                subjectDN = value;
+                break;
+            case "hash":
+                fingerprint256 = normalizeFingerprint(value);
+                break;
+            case "serial":
+                serialNumber = value;
+                break;
+            case "dns":
+                sans.push(`DNS:${value}`);
+                break;
+            case "uri":
+                sans.push(`URI:${value}`);
+                break;
+            case "cert":
+                pem = decodeURIComponentSafe(value);
+                break;
+            default:
+                break;
+        }
+    }
+    if (subjectDN === undefined &&
+        fingerprint256 === undefined &&
+        sans.length === 0 &&
+        pem === undefined) {
+        return undefined;
+    }
+    return {
+        subjectDN,
+        subjectCN: cnFromDN(subjectDN),
+        serialNumber,
+        fingerprint256,
+        subjectAltNames: sans,
+        verified: true,
+        pem,
+    };
+}
+function decodeURIComponentSafe(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+}
+const MISSING_CERT_BODY = JSON.stringify({
+    type: "https://daloyjs.dev/errors/client-certificate-required",
+    title: "Client certificate required",
+    status: 401,
+});
+/**
+ * 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 function clientCertAuth(opts = {}) {
+    const requireVerified = opts.requireVerified !== false;
+    const checkValidity = opts.checkValidity !== false;
+    const message = opts.message ?? "Client certificate not permitted";
+    const stateKey = opts.stateKey ?? "clientCertificate";
+    const now = opts.now ?? Date.now;
+    const allowFingerprints = (opts.allowFingerprints ?? []).map((f) => normalizeFingerprint(f) ?? "");
+    const allowSubjectCNs = opts.allowSubjectCNs;
+    const allowIssuerCNs = opts.allowIssuerCNs;
+    const allowSANs = opts.allowSANs;
+    const headerConfig = opts.header;
+    if (headerConfig !== undefined) {
+        assertHeaderConfig(headerConfig);
+    }
+    const resolve = opts.resolve ??
+        ((ctx) => {
+            const native = getClientCertificate(ctx.request);
+            if (native)
+                return native;
+            if (headerConfig)
+                return certFromHeaders(ctx.request, headerConfig);
+            return undefined;
+        });
+    return {
+        async beforeHandle(ctx) {
+            const cert = resolve(ctx);
+            if (!cert) {
+                return new Response(MISSING_CERT_BODY, {
+                    status: 401,
+                    headers: {
+                        "content-type": "application/problem+json",
+                        "cache-control": "no-store",
+                    },
+                });
+            }
+            if (requireVerified && !cert.verified) {
+                throw new ForbiddenError(message);
+            }
+            if (checkValidity && !isWithinValidity(cert, now())) {
+                throw new ForbiddenError(message);
+            }
+            if (allowSubjectCNs && !matchesAllowedCN(cert.subjectCN, allowSubjectCNs)) {
+                throw new ForbiddenError(message);
+            }
+            if (allowIssuerCNs && !matchesAllowedCN(cert.issuerCN, allowIssuerCNs)) {
+                throw new ForbiddenError(message);
+            }
+            if (allowFingerprints.length > 0 && !matchesFingerprint(cert, allowFingerprints)) {
+                throw new ForbiddenError(message);
+            }
+            if (allowSANs && !matchesSAN(cert.subjectAltNames, allowSANs)) {
+                throw new ForbiddenError(message);
+            }
+            if (opts.verify) {
+                const ok = await opts.verify(cert, ctx);
+                if (ok === false)
+                    throw new ForbiddenError(message);
+            }
+            ctx.state[stateKey] = cert;
+            return undefined;
+        },
+    };
+}
+function assertHeaderConfig(cfg) {
+    if (cfg.format === "xfcc")
+        return;
+    if (cfg.format === "structured") {
+        if (!cfg.subjectDN &&
+            !cfg.fingerprint &&
+            !cfg.san &&
+            !cfg.serialNumber &&
+            !cfg.issuerDN) {
+            throw new Error("clientCertAuth(): structured header config must name at least one of subjectDN/issuerDN/fingerprint/serialNumber/san.");
+        }
+        return;
+    }
+    throw new Error('clientCertAuth(): header.format must be "xfcc" or "structured".');
+}
+function certFromHeaders(request, cfg) {
+    if (cfg.format === "xfcc") {
+        const name = cfg.name ?? "x-forwarded-client-cert";
+        return parseForwardedClientCert(request.headers.get(name));
+    }
+    const subjectDN = readHeader(request, cfg.subjectDN);
+    const issuerDN = readHeader(request, cfg.issuerDN);
+    const fingerprint = normalizeFingerprint(readHeader(request, cfg.fingerprint));
+    const serialNumber = readHeader(request, cfg.serialNumber);
+    const sanRaw = readHeader(request, cfg.san);
+    const verifyRaw = cfg.verify ? readHeader(request, cfg.verify) : undefined;
+    const successValue = (cfg.verifySuccessValue ?? "SUCCESS").toLowerCase();
+    const verified = cfg.verify === undefined
+        ? true
+        : (verifyRaw ?? "").toLowerCase() === successValue;
+    const sans = [];
+    if (sanRaw) {
+        for (const piece of sanRaw.split(",")) {
+            const trimmed = piece.trim();
+            if (trimmed.length > 0)
+                sans.push(trimmed);
+        }
+    }
+    if (subjectDN === undefined &&
+        issuerDN === undefined &&
+        fingerprint === undefined &&
+        serialNumber === undefined &&
+        sans.length === 0) {
+        return undefined;
+    }
+    return {
+        subjectDN,
+        subjectCN: cnFromDN(subjectDN),
+        issuerDN,
+        issuerCN: cnFromDN(issuerDN),
+        serialNumber,
+        fingerprint256: fingerprint,
+        subjectAltNames: sans,
+        verified,
+    };
+}
+function readHeader(request, name) {
+    if (!name)
+        return undefined;
+    const value = request.headers.get(name);
+    if (value === null)
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function isWithinValidity(cert, nowMs) {
+    if (cert.notBefore && nowMs < cert.notBefore.getTime())
+        return false;
+    if (cert.notAfter && nowMs > cert.notAfter.getTime())
+        return false;
+    return true;
+}
+function matchesAllowedCN(cn, allowed) {
+    if (!cn)
+        return false;
+    for (const a of allowed) {
+        if (a === cn)
+            return true;
+    }
+    return false;
+}
+function matchesFingerprint(cert, allowed) {
+    const fp = cert.fingerprint256;
+    if (!fp)
+        return false;
+    let matched = false;
+    // Constant-time per comparison; do not early-return so we don't leak which
+    // allow-list entry matched via timing.
+    for (const a of allowed) {
+        if (timingSafeEqual(fp, a))
+            matched = true;
+    }
+    return matched;
+}
+function matchesSAN(sans, allowed) {
+    if (sans.length === 0)
+        return false;
+    for (const want of allowed) {
+        for (const have of sans) {
+            if (have === want)
+                return true;
+            // Allow matching a bare value against the `TYPE:value` form.
+            const colon = have.indexOf(":");
+            if (colon !== -1 && have.slice(colon + 1) === want)
+                return true;
+        }
+    }
+    return false;
+}

package/dist/multipart.js

@@ -236,8 +236,8 @@ async function verifyMagicBytes(file, signatures) {
 /** Shared implementation for the `fileField` overloads above. */
 export function fileField(options = {}) {
     const opts = {
-        format: options.format ?? "binary",
         ...options,
+        format: options.format ?? "binary",
     };
     const magicSignatures = normalizeMagicBytesOption(opts.magicBytes, opts.accept);
     const scriptableImagesEnabled = opts.rejectScriptableImages === undefined

package/dist/openapi-diff.d.ts

@@ -0,0 +1,79 @@
+/**
+ * `@daloyjs/core/openapi-diff` — pure, dependency-free OpenAPI 3.x diffing.
+ *
+ * Compares two OpenAPI documents (a published *baseline* and a freshly
+ * generated *current* spec) and classifies every structural change as either
+ * **breaking** (a consumer relying on the baseline could now fail) or
+ * **non-breaking** (purely additive / informational). This is the engine
+ * behind the `daloy diff` CLI command and the `verify:breaking-changes` CI
+ * gate, answering the single question a contract-first framework should make
+ * trivial: *"did this change break my published API?"*
+ *
+ * The implementation walks plain JSON and never imports a schema validator or
+ * any runtime dependency, so it can run in any environment that can read two
+ * JSON files.
+ *
+ * @module
+ * @since 0.37.0
+ */
+/** Severity classification for a single detected change. */
+export type ChangeSeverity = "breaking" | "non-breaking";
+/**
+ * A single structural difference between two OpenAPI documents.
+ */
+export interface OpenAPIChange {
+    /** Whether this change can break an existing consumer. */
+    severity: ChangeSeverity;
+    /**
+     * Stable machine-readable category, e.g. `"operation.removed"`,
+     * `"response.removed"`, `"parameter.required.added"`.
+     */
+    kind: string;
+    /** Human-readable pointer, e.g. `"GET /books/{id}"` or `"GET /books → 404"`. */
+    location: string;
+    /** Short prose describing the change. */
+    detail: string;
+}
+/** Structured result of {@link diffOpenAPI}. */
+export interface OpenAPIDiffResult {
+    /** Changes that may break an existing consumer. */
+    breaking: OpenAPIChange[];
+    /** Additive or informational changes that are safe for consumers. */
+    nonBreaking: OpenAPIChange[];
+}
+/**
+ * Compare a baseline OpenAPI document against a current one and classify the
+ * differences. The comparison is intentionally conservative: anything that
+ * could cause a request that succeeded against the baseline to fail against
+ * the current spec is reported as **breaking**; additive and metadata-only
+ * changes are reported as **non-breaking**.
+ *
+ * Detected breaking changes:
+ * - a path or operation (HTTP method) present in the baseline is removed;
+ * - a documented response status code is removed from an operation;
+ * - a new `required` parameter is added to an existing operation;
+ * - an existing optional parameter becomes `required`;
+ * - an operation's request body becomes required when it was not.
+ *
+ * Detected non-breaking changes:
+ * - new paths, operations, response codes, or optional parameters;
+ * - a parameter is removed (the server no longer reads it);
+ * - an operation becomes `deprecated`;
+ * - the document `info.version` changes.
+ *
+ * @param baseline - The previously published OpenAPI document (JSON).
+ * @param current - The freshly generated OpenAPI document (JSON).
+ * @returns Structured lists of breaking and non-breaking changes.
+ * @since 0.37.0
+ */
+export declare function diffOpenAPI(baseline: unknown, current: unknown): OpenAPIDiffResult;
+/**
+ * Convenience predicate over {@link diffOpenAPI}: `true` when the current
+ * document introduces at least one breaking change versus the baseline.
+ *
+ * @param baseline - The previously published OpenAPI document (JSON).
+ * @param current - The freshly generated OpenAPI document (JSON).
+ * @returns `true` if any breaking change was detected.
+ * @since 0.37.0
+ */
+export declare function hasBreakingChanges(baseline: unknown, current: unknown): boolean;