kinetex 1.3.0 → 1.4.0

package/dist/cjs/aws-sigv4.js

@@ -162,12 +162,61 @@ export function imdsCredentials(options = {}) {
         const credsRes = await fetchWithTimeout(`${endpoint}/latest/meta-data/iam/security-credentials/${encodeURIComponent(role)}`, { headers: { "x-aws-ec2-metadata-token": token } }, timeout);
         if (!credsRes.ok)
             throw new NetworkError(`IMDS credentials fetch failed: ${credsRes.status}`);
-        const data = (await credsRes.json());
+        // Two failures used to escape this function unlabelled, and both of them
+        // turned into a silently broken signature rather than an error:
+        //
+        //  - `Response.json()` throws a bare `SyntaxError` on a non-JSON body, so
+        //    a proxy's HTML 502 page arrived with no `code` — a caller branching
+        //    on `err.code === "ENETWORK"` never saw it, and the message said
+        //    nothing about IMDS. Every other failure here is a `NetworkError`.
+        //  - A well-formed but shapeless body parsed fine and produced a
+        //    "successful" result: `{}` yielded `accessKeyId: undefined`, and
+        //    `{"AccessKeyId": null, …}` yielded nulls. Both then went on to
+        //    produce a SigV4 signature AWS rejects with an opaque
+        //    `SignatureDoesNotMatch`, pointing at the caller rather than at the
+        //    metadata endpoint that had actually answered with nonsense.
+        let data;
+        try {
+            data = (await credsRes.json());
+        }
+        catch (err) {
+            throw new NetworkError(`IMDS credentials response was not JSON: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (data === null || typeof data !== "object") {
+            throw new NetworkError(`IMDS credentials response was not an object: ${typeof data}`);
+        }
+        const { AccessKeyId, SecretAccessKey, Token, Expiration } = data;
+        const missing = [];
+        if (typeof AccessKeyId !== "string" || AccessKeyId.length === 0)
+            missing.push("AccessKeyId");
+        if (typeof SecretAccessKey !== "string" || SecretAccessKey.length === 0)
+            missing.push("SecretAccessKey");
+        if (typeof Token !== "string" || Token.length === 0)
+            missing.push("Token");
+        if (missing.length > 0) {
+            throw new NetworkError(`IMDS credentials response is missing ${missing.join(", ")} — ` +
+                "the metadata endpoint returned a body this client cannot sign with");
+        }
+        // Re-read through a narrowing helper: the checks above report every missing
+        // field at once, which is the right message but does not let the compiler
+        // carry the narrowing into this scope.
+        const requireString = (value, name) => {
+            if (typeof value !== "string" || value.length === 0) {
+                throw new NetworkError(`IMDS credentials response is missing ${name}`);
+            }
+            return value;
+        };
+        const accessKeyId = requireString(AccessKeyId, "AccessKeyId");
+        const secretAccessKey = requireString(SecretAccessKey, "SecretAccessKey");
+        const sessionToken = requireString(Token, "Token");
         return {
-            accessKeyId: data.AccessKeyId,
-            secretAccessKey: data.SecretAccessKey,
-            sessionToken: data.Token,
-            expiration: data.Expiration,
+            accessKeyId,
+            secretAccessKey,
+            sessionToken,
+            // Optional: a role without an expiry is legal, and the signer treats a
+            // missing expiration as "do not cache". Omitted rather than set to
+            // `undefined` — the project uses exactOptionalPropertyTypes.
+            ...(typeof Expiration === "string" ? { expiration: Expiration } : {}),
         };
     });
 }
@@ -339,6 +388,12 @@ function buildCanonicalHeaders(headers, unsignedExtra) {
     const entries = [];
     for (const [name, value] of Object.entries(headers)) {
         const lower = name.toLowerCase();
+        // An empty header name is not a valid HTTP field-name (RFC 9110 §5.1) and
+        // used to reach the canonical request verbatim, producing a `:value` line
+        // and a leading `;` in SignedHeaders. AWS answers that with an opaque
+        // SignatureDoesNotMatch rather than saying the header name was empty.
+        if (lower === "")
+            continue;
         if (unsigned.has(lower) && !ALWAYS_SIGNED_HEADERS.has(lower))
             continue;
         // Trim + collapse internal whitespace
@@ -446,10 +501,19 @@ export async function signRequest(request, config) {
     const amzDate = formatAmzDate(signingDate);
     const dateStamp = formatDateStamp(signingDate);
     const parsedUrl = new URL(request.url);
-    // Build the headers to sign — start from request headers
+    // Build the headers to sign — start from request headers.
+    //
+    // An explicitly-supplied `host` (in any casing) must WIN. Setting it is how
+    // you sign for a virtual-hosted-style bucket, a custom endpoint or a proxy.
+    // The URL host used to be injected unconditionally, which left both keys in
+    // the map whenever the caller used a different casing; `buildCanonicalHeaders`
+    // lowercased them and its dedupe step joined them, so the request was signed
+    // as `host:override.example,s3.amazonaws.com` — a host that can never
+    // validate, and one the library reported no error about.
+    const hasExplicitHost = Object.keys(request.headers).some((k) => k.toLowerCase() === "host");
     const headers = {
         ...request.headers,
-        host: parsedUrl.host,
+        ...(hasExplicitHost ? {} : { host: parsedUrl.host }),
         "x-amz-date": amzDate,
     };
     if (config.unsignedPayload) {
@@ -498,11 +562,22 @@ export async function presignRequest(request, config, options = {}) {
     const signingDate = resolveSigningDate(config);
     const amzDate = formatAmzDate(signingDate);
     const dateStamp = formatDateStamp(signingDate);
-    const expiresIn = options.expiresIn ?? 3600;
-    // Validate expiresIn range - different services have different limits
+    // Validate and CLAMP expiresIn. AWS enforces a hard maximum per service and
+    // rejects an out-of-range or fractional value with an opaque
+    // AuthorizationQueryParametersError at use time, long after the URL was
+    // handed out. The old code logged a warning and then wrote the caller's
+    // number straight into the query string, so `expiresIn: 0` produced
+    // `X-Amz-Expires=0`, `expiresIn: -1` produced `=-1`, and `expiresIn: 1e9`
+    // produced a link valid for ~31 years — every one of them permanently
+    // unusable, with a console warning as the only signal. Clamping can only
+    // shorten a link, never lengthen one, so it is the safe direction.
     const maxExpires = config.service === "s3" ? 604800 : 3600;
-    if (expiresIn < 1 || expiresIn > maxExpires) {
-        console.warn(`[aws-sigv4] presignRequest: expiresIn should be 1-${maxExpires} seconds for ${config.service}, got ${expiresIn}`);
+    const requested = options.expiresIn ?? 3600;
+    const expiresIn = Number.isFinite(requested)
+        ? Math.min(Math.max(Math.floor(requested), 1), maxExpires)
+        : maxExpires;
+    if (expiresIn !== requested) {
+        console.warn(`[aws-sigv4] presignRequest: expiresIn must be an integer in 1-${maxExpires} for ${config.service}, got ${requested} — clamped to ${expiresIn}`);
     }
     const parsedUrl = new URL(request.url);
     const credentialScope = `${dateStamp}/${config.region}/${config.service}/aws4_request`;
@@ -520,10 +595,14 @@ export async function presignRequest(request, config, options = {}) {
             parsedUrl.searchParams.set(k, v);
         }
     }
-    // Determine signed headers (only "host" for presigned URLs typically)
+    // Determine signed headers (only "host" for presigned URLs typically).
+    // An explicit `host` wins here for the same reason it does in sign() — a
+    // differently-cased caller header used to be merged with the URL host into
+    // `host:override.example,s3.amazonaws.com`, which can never validate.
+    const presignHasExplicitHost = Object.keys(request.headers).some((k) => k.toLowerCase() === "host");
     const headers = {
         ...request.headers,
-        host: parsedUrl.host,
+        ...(presignHasExplicitHost ? {} : { host: parsedUrl.host }),
     };
     const unsignedHdrs = config.unsignedHeaders ?? [];
     // For presigned URLs, payload hash is always UNSIGNED-PAYLOAD
@@ -666,14 +745,49 @@ export async function signS3PostPolicy(policy, config) {
  * Returns 0 if the header is absent or unparseable.
  */
 export function detectClockSkew(responseHeaders) {
-    const dateHeader = responseHeaders["date"] ?? responseHeaders["Date"];
-    if (!dateHeader)
-        return 0;
-    const serverTime = new Date(dateHeader).getTime();
-    if (isNaN(serverTime))
-        return 0;
+    // `x-amz-date` is AWS's own signed timestamp and is the one present on the
+    // clock-skew error itself. `Date` is generated by whatever proxy fronts the
+    // endpoint and is frequently absent. Reading only `Date` meant a skew was
+    // silently undetectable on exactly the responses that carry it.
+    const amzDate = responseHeaders["x-amz-date"] ?? responseHeaders["X-Amz-Date"];
+    let serverTime;
+    if (amzDate !== undefined) {
+        serverTime = parseAmzDate(amzDate);
+        if (isNaN(serverTime))
+            return 0;
+    }
+    else {
+        const dateHeader = responseHeaders["date"] ?? responseHeaders["Date"];
+        if (!dateHeader)
+            return 0;
+        serverTime = new Date(dateHeader).getTime();
+        if (isNaN(serverTime))
+            return 0;
+    }
     return Math.round((serverTime - Date.now()) / 1000);
 }
+/**
+ * Parse AWS's basic ISO 8601 timestamp (`20300101T120000Z`), which is not a
+ * form `Date` can parse.
+ *
+ * @param value - Candidate `x-amz-date` value
+ * @returns Epoch milliseconds, or `NaN` when the value is not in that form
+ */
+function parseAmzDate(value) {
+    const m = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z$/.exec(value.trim());
+    if (!m)
+        return NaN;
+    const [, y, mo, d, h, mi, sec] = m;
+    // Reject values that roll over silently (e.g. month 13) instead of
+    // producing a date in the following month.
+    const t = Date.UTC(Number(y), Number(mo) - 1, Number(d), Number(h), Number(mi), Number(sec));
+    const dt = new Date(t);
+    if (dt.getUTCFullYear() !== Number(y) || dt.getUTCMonth() + 1 !== Number(mo))
+        return NaN;
+    if (dt.getUTCDate() !== Number(d))
+        return NaN;
+    return t;
+}
 /**
  * Determine if an error response is a clock skew error.
  */

package/dist/cjs/cache.js

@@ -425,6 +425,12 @@ async function defaultCacheKey(req) {
  * Compute cache TTL, SWR window, and stale-on-error window
  * from Cache-Control headers, Expires header, or Last-Modified heuristic.
  */
+/** True when the response may be stored but must be revalidated before reuse. */
+function computeMustRevalidate(response) {
+    const cc = response.headers["cache-control"] ?? response.headers["Cache-Control"] ?? "";
+    const d = parseCacheControl(cc);
+    return d.noCache || d.mustRevalidate;
+}
 function computeTTL(response, defaultTtl, honor) {
     const cc = response.headers["cache-control"] ?? response.headers["Cache-Control"] ?? "";
     const d = parseCacheControl(cc);
@@ -453,7 +459,15 @@ function computeTTL(response, defaultTtl, honor) {
             if (lm) {
                 const lmTime = Date.parse(lm);
                 if (!isNaN(lmTime)) {
-                    ttlMs = Math.min((Date.now() - lmTime) * 0.1, defaultTtl);
+                    // RFC 9111 §4.2.2: the heuristic lifetime is 10% of the interval
+                    // between Last-Modified and the response's Date. That interval is
+                    // negative whenever Last-Modified is in the future — routine, since
+                    // the origin and the client rarely share a clock — and there was no
+                    // lower clamp, so the entry was given a negative freshness lifetime
+                    // and a staleUntil *before* its creation time. The clamp to 0 is the
+                    // RFC's "already stale"; the stale windows then apply normally,
+                    // instead of landing in the past and being unreachable.
+                    ttlMs = Math.min(Math.max((Date.now() - lmTime) * 0.1, 0), defaultTtl);
                 }
                 else {
                     ttlMs = defaultTtl;
@@ -474,7 +488,11 @@ function computeTTL(response, defaultTtl, honor) {
         ttlMs,
         swrMs,
         staleOnError,
-        shouldCache: ttlMs > 0 || swrMs > 0,
+        // Storable if it is fresh now, or already stale but covered by a
+        // stale-while-revalidate / stale-if-error window. The two windows were
+        // missing from this decision, so `max-age=0, stale-if-error=60` — the
+        // point of the directive — was reported as uncacheable.
+        shouldCache: ttlMs > 0 || swrMs > 0 || staleOnError > 0,
     };
 }
 // ============================================================================
@@ -674,7 +692,12 @@ export class HTTPCache {
             this.stats.hits++;
             this.lru.touch(key);
             this._updateHitRate();
-            return { entry: cloneEntry(entry), stale: false };
+            // RFC 9111 §5.2.2.4: a `no-cache` response may be stored but must not be
+            // reused without revalidating. It used to be reported as a plain fresh
+            // hit, so an origin that sent `Cache-Control: no-cache` had its response
+            // served indefinitely from cache. Reporting it as stale routes it into the
+            // existing serve-stale-and-revalidate path instead.
+            return { entry: cloneEntry(entry), stale: entry.mustRevalidate === true };
         }
         // Stale-While-Revalidate window
         if (entry.staleUntil > now) {
@@ -722,7 +745,14 @@ export class HTTPCache {
         // 9.10 — cap TTL to maxAbsoluteAgeMs so stored entries can never outlive the limit
         const absoluteCap = this.cfg.maxAbsoluteAgeMs;
         const cappedTtlMs = Math.min(ttlMs === Infinity ? absoluteCap : ttlMs, absoluteCap);
-        if (cappedTtlMs <= 0 && !options.force)
+        // A zero (or negative) freshness lifetime does not by itself mean
+        // "unstoreable": RFC 9111 §4.2 still permits storing a response that is
+        // already stale, provided a stale-while-revalidate or stale-if-error
+        // window covers it — and `computeTTL` has just told us exactly that via
+        // `shouldCache`. This guard used to discard that decision, so the canonical
+        // CDN recipe `Cache-Control: max-age=0, stale-while-revalidate=60` was
+        // never cached at all, defeating the one directive it exists to enable.
+        if (cappedTtlMs <= 0 && swrMs <= 0 && staleOnError <= 0 && !options.force)
             return false;
         const varyHeader = res.headers["vary"] ?? res.headers["Vary"] ?? null;
         const varyKey = varyHeader ? buildVaryKey(varyHeader, req.headers) : "";
@@ -739,6 +769,7 @@ export class HTTPCache {
             etag: res.headers["etag"] ?? res.headers["ETag"] ?? null,
             lastModified: res.headers["last-modified"] ?? res.headers["Last-Modified"] ?? null,
             varyKey,
+            mustRevalidate: computeMustRevalidate(res),
             tags,
             size: bodySize + 256,
         };
@@ -909,16 +940,27 @@ export class HTTPCache {
     getStats() {
         return { ...this.stats };
     }
-    /** Reset all cache statistics to zero. */
+    /**
+     * Reset the cache's counters to zero.
+     *
+     * `totalEntries` and `totalSizeBytes` are deliberately NOT reset: they are
+     * gauges of what is actually stored, not counters of events, and
+     * `_ensureCapacity()` reads them as the authoritative figures for the
+     * `maxEntries` / `maxSizeBytes` caps. Zeroing them while the entries are
+     * still in storage made eviction compare against a fiction — a cache with
+     * `maxSizeBytes: 600` was measured holding 1028 bytes across 4 entries
+     * after a reset — and made `getStats().totalEntries` report 0 for entries
+     * that were still there and still being served. Call `clear()` to empty the
+     * cache; use this to zero the hit/miss/eviction counters.
+     */
     resetStats() {
         this.stats = {
+            ...this.stats,
             hits: 0,
             misses: 0,
             staleHits: 0,
             errors: 0,
             evictions: 0,
-            totalEntries: 0,
-            totalSizeBytes: 0,
             hitRate: 0,
         };
     }

package/dist/cjs/circuit-breaker.js

@@ -29,7 +29,11 @@ export class CircuitOpenError extends Error {
      * @param state - Snapshot of breaker state at rejection time
      */
     constructor(key, state) {
-        super(`Circuit breaker OPEN for "${key}" — request rejected`);
+        // The half-open probe limit rejects callers too, and in that case
+        // `state.state` is HALF_OPEN: the circuit is recovering, not open. Saying
+        // "OPEN" there pointed operators at the wrong problem during exactly the
+        // window they were watching to see recovery.
+        super(`Circuit breaker ${state.state} for "${key}" — request rejected`);
         this.name = "CircuitOpenError";
         this.state = state;
     }
@@ -97,6 +101,22 @@ export class CircuitBreaker {
         this.key = key;
         this.failureThreshold = config.failureThreshold ?? 5;
         this.windowSize = config.windowSize ?? 10;
+        // The window is a sliding buffer of the most recent `windowSize` results,
+        // so it can hold at most `windowSize` failures. If the window is smaller
+        // than the threshold, `failures >= failureThreshold` is unreachable and
+        // the circuit can never open — a breaker that silently does nothing, with
+        // no error and no other symptom. `{ windowSize: 2, failureThreshold: 5 }`
+        // stayed CLOSED through 50 consecutive failures. The window is widened to
+        // the threshold instead, which is the smallest coherent reading of the
+        // configuration. windowSize: 0 is the documented consecutive-count mode
+        // and is left alone.
+        if (this.windowSize > 0 && this.windowSize < this.failureThreshold) {
+            console.warn(`[CircuitBreaker] "${key}": windowSize (${this.windowSize}) is smaller than ` +
+                `failureThreshold (${this.failureThreshold}), so the threshold could never be ` +
+                `reached and the circuit would never open. Raising windowSize to ` +
+                `${this.failureThreshold}.`);
+            this.windowSize = this.failureThreshold;
+        }
         this.resetTimeoutMs = config.resetTimeoutMs ?? 30_000;
         this.successThreshold = config.successThreshold ?? 2;
         this.halfOpenConcurrency = config.halfOpenConcurrency ?? 1;
@@ -109,8 +129,27 @@ export class CircuitBreaker {
         this.cfg = config;
     }
     // ── Public API ──────────────────────────────────────────────────────────
-    /** The current circuit state. */
+    /**
+     * The current circuit state, as of right now.
+     *
+     * The OPEN → HALF_OPEN transition is driven by elapsed time, but it was only
+     * ever evaluated inside `execute()`. A caller reading `state` — a health
+     * endpoint, a dashboard, the `onRejected` snapshot — therefore saw a stale
+     * `OPEN` for as long as no traffic arrived, and could not tell a circuit
+     * that was about to probe from one that had been down for an hour. The
+     * elapsed check is applied on read as well. It is a pure read: the
+     * `onHalfOpen` callback still fires from `execute()`, so observing the state
+     * never mutates the breaker.
+     */
     get state() {
+        return this._effectiveState();
+    }
+    /** The state implied by `_state` and the elapsed time, without mutating anything. */
+    _effectiveState() {
+        if (this._state === "OPEN" && this._openedAt !== null) {
+            if (Date.now() - this._openedAt >= this.resetTimeoutMs)
+                return "HALF_OPEN";
+        }
         return this._state;
     }
     /** Snapshot of all counters — suitable for logging or dashboards. */
@@ -125,7 +164,10 @@ export class CircuitBreaker {
                     failureCount++;
         }
         return {
-            state: this._state,
+            // Time-derived, for the same reason as the `state` getter: a snapshot
+            // taken between the reset window elapsing and the next request would
+            // otherwise report a circuit as OPEN when it is ready to probe.
+            state: this._effectiveState(),
             failureCount,
             successCount: this._consecutiveSucc,
             lastFailureAt: this._lastFailureAt,