@apifuse/provider-sdk 2.2.0-beta.12 → 2.2.0-beta.13

package/dist/runtime/stealth.js

@@ -6,7 +6,7 @@ import { SDKError, StealthCookieStoreVersionError, TransportError } from "../err
 import { getStealthProfile } from "../stealth/profiles.js";
 import { createProxyAuthIpDeniedError, createProxyEdgeAuthRejectedError, createProxyEdgeTlsRejectedError, createProxyPoolExhaustedError, createProxyPoolStaleError, isProxyAuthIpDeniedMessage, isProxyEdgeAuthRejectedMessage, isProxyEdgeTlsRejectedResponse, isProxyPoolRefreshableError, isProxyPoolStaleMessage, isProxyPoolStaleStatus, PROXY_EDGE_AUTH_REJECTED_CODE, PROXY_POOL_STALE_CODE, } from "./proxy-errors.js";
 import { computeProxyAttemptIndex, computeProxyTransportRetryDelayMs, createDefaultProxyTransportRetryOptions, normalizeProxyTransportRetryOptions, shouldRetryProxyTransportAttempt, validateUnsafeProxyTransportRetryMethods, } from "./proxy-retry-policy.js";
-import { appendQueryParams } from "./request-options.js";
+import { isSensitiveKey, redactSensitiveError, redactSensitiveRequestError, redactSensitiveText, redactUrlQueryParams, normalizeSensitiveParams, serializeRequestUrl, } from "./request-options.js";
 const DEFAULT_PROFILE = "chrome-146";
 const MISSING_PROXY_WARNING = "[provider-sdk] Provider requested proxy routing, but no proxy URL was configured. Continuing without proxy.";
 const MAX_POLICY_PROXY_POOL_REFRESHES = 1;
@@ -15,6 +15,14 @@ const PROXY_CONNECT_FAILURE_BODY_PATTERN = /\bproxy\b.*\b(non[\s-]?200|connect|t
 const PROXY_AUTH_DIAGNOSTIC_URL = "http://example.com/";
 const PROXY_AUTH_DIAGNOSTIC_TIMEOUT_MS = 5_000;
 const STEALTH_PROXY_TRANSPORT_RETRY_ERROR_CODES = [PROXY_CONNECT_FAILURE_CODE];
+function sensitiveQueryParamNames(url) {
+    const queryStart = url.indexOf("?");
+    if (queryStart === -1)
+        return [];
+    const fragmentStart = url.indexOf("#", queryStart);
+    const query = url.slice(queryStart + 1, fragmentStart === -1 ? undefined : fragmentStart);
+    return [...new URLSearchParams(query).keys()].filter(isSensitiveKey);
+}
 const REMOVED_CHROME_PROFILE_NAMES = new Set([
     "chrome-120",
     "chrome-124",
@@ -293,10 +301,12 @@ function splitCombinedSetCookieHeader(headerValue) {
         cookieStrings.push(finalCookie);
     return cookieStrings;
 }
-export async function normalizeResponse(response, requestUrl) {
+export async function normalizeResponse(response, requestUrl, maxBodyBytes) {
     const headers = Object.fromEntries(response.headers.entries());
     const cookies = new CookieJarImpl(setCookieHeadersFromResponse(response.headers), response.url ?? requestUrl);
-    const bodyBytes = await response.arrayBuffer();
+    const bodyBytes = maxBodyBytes === undefined
+        ? await response.arrayBuffer()
+        : await readResponseBodyWithLimit(response, maxBodyBytes);
     const body = new TextDecoder().decode(bodyBytes);
     return {
         status: response.status,
@@ -322,6 +332,75 @@ export async function normalizeResponse(response, requestUrl) {
         },
     };
 }
+function responseTooLargeError(maxBodyBytes, observedBytes) {
+    return new TransportError(`Response body exceeded maxBodyBytes limit of ${maxBodyBytes} bytes (observed ${observedBytes} bytes)`, {
+        code: "response_too_large",
+        category: "upstream_http",
+        retryable: false,
+        status: 0,
+    });
+}
+function declaredContentLength(headers) {
+    const contentLength = headers.get("content-length")?.trim();
+    if (!contentLength || !/^\d+$/.test(contentLength))
+        return undefined;
+    const parsed = Number(contentLength);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+function abortTransportResponse(response) {
+    if (!response.abort)
+        return false;
+    try {
+        response.abort();
+    }
+    catch {
+        // The size error remains the primary failure if impit has already closed the response.
+    }
+    return true;
+}
+async function readResponseBodyWithLimit(response, maxBodyBytes) {
+    const contentLength = declaredContentLength(response.headers);
+    if (contentLength !== undefined && contentLength > maxBodyBytes) {
+        if (!abortTransportResponse(response)) {
+            await response.body?.cancel().catch(() => undefined);
+        }
+        throw responseTooLargeError(maxBodyBytes, contentLength);
+    }
+    if (!response.body) {
+        throw new TransportError("Response body stream is unavailable", {
+            code: "transport_stream_unavailable",
+            category: "upstream_http",
+            status: 0,
+        });
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let receivedBytes = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            receivedBytes += value.byteLength;
+            if (receivedBytes > maxBodyBytes) {
+                await reader.cancel().catch(() => undefined);
+                abortTransportResponse(response);
+                throw responseTooLargeError(maxBodyBytes, receivedBytes);
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const bodyBytes = new Uint8Array(receivedBytes);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bodyBytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bodyBytes.buffer;
+}
 function normalizeBody(body) {
     if (body === undefined) {
         return "";
@@ -552,21 +631,29 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
     }
     const session = {
         async fetch(url, options = {}) {
-            const method = normalizeMethod(options.method ?? "GET");
-            const hasExplicitRetryPolicy = options.retry !== undefined;
-            const stealthRetryOptions = normalizeProxyTransportRetryOptions(options.retry, {
-                extraErrorCodes: STEALTH_PROXY_TRANSPORT_RETRY_ERROR_CODES,
-                label: "Stealth",
-            }) ??
-                (hasExplicitRetryPolicy
-                    ? undefined
-                    : createDefaultProxyTransportRetryOptions({
+            const { hasExplicitRetryPolicy, method, stealthRetryOptions } = (() => {
+                try {
+                    const method = normalizeMethod(options.method ?? "GET");
+                    const hasExplicitRetryPolicy = options.retry !== undefined;
+                    const stealthRetryOptions = normalizeProxyTransportRetryOptions(options.retry, {
                         extraErrorCodes: STEALTH_PROXY_TRANSPORT_RETRY_ERROR_CODES,
                         label: "Stealth",
-                    }));
-            if (stealthRetryOptions) {
-                validateUnsafeProxyTransportRetryMethods(stealthRetryOptions, "Stealth");
-            }
+                    }) ??
+                        (hasExplicitRetryPolicy
+                            ? undefined
+                            : createDefaultProxyTransportRetryOptions({
+                                extraErrorCodes: STEALTH_PROXY_TRANSPORT_RETRY_ERROR_CODES,
+                                label: "Stealth",
+                            }));
+                    if (stealthRetryOptions) {
+                        validateUnsafeProxyTransportRetryMethods(stealthRetryOptions, "Stealth");
+                    }
+                    return { hasExplicitRetryPolicy, method, stealthRetryOptions };
+                }
+                catch (error) {
+                    throw redactSensitiveRequestError(error, url, options.sensitiveParams);
+                }
+            })();
             const hasPolicyProxy = isPolicyManagedProxy(clientOptions);
             const usesPolicyAllocator = hasPolicyProxy && !options.proxy && !clientOptions.proxy;
             const retryAttemptCap = Math.max(1, stealthRetryOptions?.attempts ?? 1);
@@ -600,6 +687,11 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                 for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
                     let proxy;
                     let attemptProxy;
+                    // Reuse the exact serialization used by this outbound attempt in its catch path.
+                    let serializedUrl;
+                    let fallbackSensitiveValues = [];
+                    let fallbackRequestUrl;
+                    let fallbackRedactedUrl;
                     const attemptStartedAt = Date.now();
                     let attemptRecorded = false;
                     const recordProxyAttempt = (outcome, errorCode, status) => {
@@ -620,6 +712,16 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                         });
                     };
                     try {
+                        const sensitiveParams = normalizeSensitiveParams(options.sensitiveParams);
+                        const structural = redactUrlQueryParams(url, Object.keys(sensitiveParams ?? {}));
+                        fallbackSensitiveValues = [
+                            ...new Set([
+                                ...Object.values(sensitiveParams ?? {}).map(String),
+                                ...structural.sensitiveValues,
+                            ]),
+                        ].filter((value) => value !== "");
+                        fallbackRequestUrl = url;
+                        fallbackRedactedUrl = structural.redactedUrl;
                         assertNoUnsupportedFingerprintOverrides(options);
                         attemptProxy = await resolveRequestProxy(options, attempt, refreshAttempt);
                         proxy = attemptProxy.url;
@@ -637,7 +739,8 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                         const ignoreTlsErrors = Boolean(options.stealth?.insecureSkipVerify ??
                             (!hasPolicyProxy && proxy && clientOptions.proxyStealth?.insecureSkipVerify));
                         const profileName = options.profile ?? defaultProfile;
-                        const requestUrl = appendQueryParams(resolveUrl(baseUrl, url), options.params);
+                        serializedUrl = serializeRequestUrl(resolveUrl(baseUrl, url), options.params, sensitiveParams);
+                        const { requestUrl } = serializedUrl;
                         const headers = { ...(options.headers ?? {}) };
                         if (!hasHeader(headers, "Cookie")) {
                             const cookieHeader = cookieJar.toHeader(requestUrl);
@@ -654,7 +757,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                             requestInit.body = normalizeBody(options.body);
                         }
                         const response = await getClient(profileName, proxy, ignoreTlsErrors).fetch(requestUrl, requestInit);
-                        const normalized = await normalizeResponse(response, requestUrl);
+                        const normalized = await normalizeResponse(response, requestUrl, options.maxBodyBytes);
                         cookieJar.setFromCookieStrings(setCookieHeadersFromResponse(response.headers), response.url ?? requestUrl);
                         if (proxy && isProxyConnectFailureResponse(response, normalized.body)) {
                             throw createProxyConnectFailureError(normalized.body);
@@ -687,12 +790,23 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                         return normalized;
                     }
                     catch (error) {
-                        const normalizedError = normalizeStealthTransportError(error);
+                        const sensitiveValues = serializedUrl?.sensitiveValues ?? fallbackSensitiveValues;
+                        let normalizedError;
+                        try {
+                            normalizedError = normalizeStealthTransportError(error);
+                        }
+                        catch (normalizationError) {
+                            throw redactSensitiveError(normalizationError, sensitiveValues, serializedUrl?.requestUrl ?? fallbackRequestUrl, serializedUrl?.redactedUrl ?? fallbackRedactedUrl);
+                        }
+                        const retryErrorCode = proxyAttemptErrorCode(normalizedError);
+                        const refreshableProxyError = isProxyPoolRefreshableError(normalizedError);
+                        const runProxyAuthDiagnostic = shouldRunProxyAuthDiagnostic(normalizedError);
+                        normalizedError = redactSensitiveError(normalizedError, sensitiveValues, serializedUrl?.requestUrl ?? fallbackRequestUrl, serializedUrl?.redactedUrl ?? fallbackRedactedUrl);
                         recordProxyAttempt("error", proxyAttemptErrorCode(normalizedError), proxyAttemptStatus(normalizedError));
                         lastError = normalizedError;
-                        if (proxy && rotatesRegistryChain && isProxyPoolRefreshableError(normalizedError)) {
+                        if (proxy && rotatesRegistryChain && refreshableProxyError) {
                             stalePoolError = normalizedError;
-                            if (shouldRunProxyAuthDiagnostic(normalizedError)) {
+                            if (runProxyAuthDiagnostic) {
                                 stalePoolDiagnosticProxy = proxy;
                             }
                             if (attempt + 1 < maxAttempts) {
@@ -722,7 +836,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                         });
                         if (attempt + 1 < transportRetryCap &&
                             shouldRetryProxyTransportAttempt({
-                                error: normalizedError,
+                                error: { code: retryErrorCode },
                                 explicitRetry: hasExplicitRetryPolicy,
                                 method,
                                 options: stealthRetryOptions,
@@ -772,23 +886,78 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                 const maxHops = options.maxHops === undefined || !Number.isFinite(options.maxHops)
                     ? 10
                     : Math.max(0, Math.floor(options.maxHops));
+                const { url: _url, maxHops: _maxHops, stopWhen, params, sensitiveParams, ...fetchOptions } = options;
                 const hops = [];
-                let currentUrl = resolveUrl(baseUrl, options.url);
                 let method = normalizeMethod(options.method ?? "GET");
                 let body = options.body;
                 let response;
                 const visitedRequests = new Set();
-                const { url: _url, maxHops: _maxHops, stopWhen, params, ...fetchOptions } = options;
+                const initialParams = params
+                    ? Object.fromEntries(Object.entries(params).map(([key, value]) => [
+                        key,
+                        Array.isArray(value) ? [...value] : value,
+                    ]))
+                    : undefined;
+                const normalizedSensitiveParams = normalizeSensitiveParams(sensitiveParams);
+                const initialSensitiveParams = normalizedSensitiveParams
+                    ? { ...normalizedSensitiveParams }
+                    : undefined;
+                const sensitiveParamNames = initialSensitiveParams
+                    ? Object.keys(initialSensitiveParams)
+                    : [];
+                const callerStructural = redactUrlQueryParams(options.url, sensitiveParamNames);
+                const sensitiveValues = new Set([
+                    ...Object.values(initialSensitiveParams ?? {}),
+                    ...callerStructural.sensitiveValues,
+                ].filter((value) => value !== ""));
+                const redactRedirectUrl = (value) => {
+                    const structural = redactUrlQueryParams(value, [
+                        ...new Set([...sensitiveParamNames, ...sensitiveQueryParamNames(value)]),
+                    ]);
+                    for (const sensitiveValue of structural.sensitiveValues) {
+                        sensitiveValues.add(sensitiveValue);
+                    }
+                    return redactSensitiveText(structural.redactedUrl, [...sensitiveValues]);
+                };
+                let currentUrl;
+                let initialUrl;
+                try {
+                    currentUrl = resolveUrl(baseUrl, options.url);
+                    redactRedirectUrl(currentUrl);
+                    initialUrl = serializeRequestUrl(currentUrl, initialParams, initialSensitiveParams);
+                    for (const value of initialUrl.sensitiveValues) {
+                        if (value !== "")
+                            sensitiveValues.add(value);
+                    }
+                }
+                catch (error) {
+                    throw redactSensitiveError(error, [...sensitiveValues], options.url, redactRedirectUrl(options.url));
+                }
                 for (let hopIndex = 0; hopIndex <= maxHops; hopIndex += 1) {
-                    visitedRequests.add(`${method} ${currentUrl}`);
-                    response = await session.fetch(currentUrl, {
-                        ...fetchOptions,
-                        body,
-                        method,
-                        ...(hopIndex === 0 && params ? { params } : {}),
-                        redirect: "manual",
-                        throwOnHttpError: false,
-                    });
+                    const outboundUrl = hopIndex === 0 ? initialUrl.requestUrl : serializeRequestUrl(currentUrl).requestUrl;
+                    // Preserve params-only loop bookkeeping from before sensitiveParams:
+                    // the first visited key is the caller's resolved URL, not its expanded query.
+                    const visitedUrl = hopIndex === 0 && !initialSensitiveParams ? currentUrl : outboundUrl;
+                    visitedRequests.add(`${method} ${visitedUrl}`);
+                    try {
+                        response = await session.fetch(currentUrl, {
+                            ...fetchOptions,
+                            body,
+                            method,
+                            ...(hopIndex === 0 && initialParams ? { params: initialParams } : {}),
+                            ...(hopIndex === 0 && initialSensitiveParams
+                                ? { sensitiveParams: initialSensitiveParams }
+                                : {}),
+                            redirect: "manual",
+                            throwOnHttpError: false,
+                        });
+                    }
+                    catch (error) {
+                        throw redactSensitiveError(error, [...sensitiveValues], outboundUrl, redactRedirectUrl(outboundUrl));
+                    }
+                    // StealthResponse.url is programmatic metadata and remains raw. Only the
+                    // redirect hop emitted below is a diagnostic surface.
+                    const responseUrl = response.url ?? (hopIndex === 0 && initialSensitiveParams ? outboundUrl : currentUrl);
                     if (!isRedirectStatus(response.status)) {
                         return {
                             final: response,
@@ -799,18 +968,49 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                         };
                     }
                     const location = locationHeader(response.headers);
-                    const nextUrl = location
-                        ? new URL(location, response.url ?? currentUrl).toString()
-                        : undefined;
-                    const hop = {
-                        url: response.url ?? currentUrl,
+                    const redactedResponseUrl = redactRedirectUrl(responseUrl);
+                    const redactedLocation = location ? redactRedirectUrl(location) : undefined;
+                    let nextUrl;
+                    try {
+                        nextUrl = location ? new URL(location, responseUrl).toString() : undefined;
+                    }
+                    catch (error) {
+                        throw redactSensitiveError(error, [...sensitiveValues], location, redactedLocation);
+                    }
+                    const realHop = {
+                        url: responseUrl,
                         status: response.status,
                         method,
                         ...(location ? { location } : {}),
                         ...(nextUrl ? { nextUrl } : {}),
                     };
+                    const hop = {
+                        ...realHop,
+                        url: redactedResponseUrl,
+                        ...(redactedLocation ? { location: redactedLocation } : {}),
+                        ...(nextUrl ? { nextUrl: redactRedirectUrl(nextUrl) } : {}),
+                    };
                     hops.push(hop);
-                    if (stopWhen && (await stopWhen(hop))) {
+                    let shouldStop = false;
+                    if (stopWhen) {
+                        try {
+                            shouldStop = await stopWhen(realHop);
+                        }
+                        catch (error) {
+                            let sanitizedError = error;
+                            for (const [rawUrl, safeUrl] of [
+                                [responseUrl, redactedResponseUrl],
+                                [location, redactedLocation],
+                                [nextUrl, nextUrl ? redactRedirectUrl(nextUrl) : undefined],
+                            ]) {
+                                if (!rawUrl || !safeUrl)
+                                    continue;
+                                sanitizedError = redactSensitiveError(sanitizedError, [...sensitiveValues], rawUrl, safeUrl);
+                            }
+                            throw sanitizedError;
+                        }
+                    }
+                    if (shouldStop) {
                         return {
                             final: response,
                             hops,

package/dist/server/index.d.ts

@@ -1,6 +1,6 @@
 export { createServerApp, type ProviderServerCloseOptions, type ProviderServerHandle, type ProviderServerLogEvent, type ProviderServerLogger, type ProviderServerOperationExecutor, type ProviderServerOperationExecutorInput, type ProviderServerOptions, type ProviderServerStatefulForwardEnvelope, type ServeOptions, serve, } from "./serve.js";
 export { computeSelfTestPlanDigest, createSelfTestApp, createSelfTestAuthFlowInvoke, createSelfTestInvoke, DEFAULT_SELF_TEST_REQUEST_BUDGET_MS, isSelfTestReadOnlyOperation, PROVIDER_RUNTIME_SELF_TEST_REQUEST_BUDGET_MS_ENV, resolveSelfTestPort, SELF_TEST_AUTH_FLOW_MULTI_TURN_SKIP_REASON, SELF_TEST_AUTH_FLOW_REJECTED_SKIP_REASON, SELF_TEST_HEALTHZ_PATH, SELF_TEST_PATH, SELF_TEST_SCHEMA_VERSION, type SelfTestAppOptions, type SelfTestAuthFlowInvoke, type SelfTestAuthFlowRoute, type SelfTestCaseResult, type SelfTestCaseStatus, type SelfTestOperationInvoke, type SelfTestRequest, SelfTestRequestSchema, type SelfTestResponse, } from "./self-test.js";
-export { resolveHealthCheckInputDateTokens } from "./self-test-input-tokens.js";
+export { type InputDateTokenCalendar, resolveHealthCheckInputDateTokens, } from "./self-test-input-tokens.js";
 export { collectSelfTestSensitiveValues, redactSelfTestText, SELF_TEST_MAX_TEXT_LENGTH, SELF_TEST_REDACTED_PLACEHOLDER, } from "./self-test-redaction.js";
 export { DEFAULT_SELF_TEST_PORT, deriveSelfTestToken, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_ENV, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_PREVIOUS_ENV, PROVIDER_RUNTIME_SELF_TEST_PORT_ENV, resolveSelfTestMasterSecrets, type SelfTestMasterSecrets, verifySelfTestAuthorization, } from "./self-test-token.js";
 export type { AuthFlowRequest, AuthFlowResponse, AuthFlowSuccessResponse, ConnectionMode, OperationConnection, OperationErrorResponse, OperationRequest, OperationResponse, OperationSuccessResponse, } from "./types.js";

package/dist/server/index.js

@@ -1,6 +1,6 @@
 export { createServerApp, serve, } from "./serve.js";
 export { computeSelfTestPlanDigest, createSelfTestApp, createSelfTestAuthFlowInvoke, createSelfTestInvoke, DEFAULT_SELF_TEST_REQUEST_BUDGET_MS, isSelfTestReadOnlyOperation, PROVIDER_RUNTIME_SELF_TEST_REQUEST_BUDGET_MS_ENV, resolveSelfTestPort, SELF_TEST_AUTH_FLOW_MULTI_TURN_SKIP_REASON, SELF_TEST_AUTH_FLOW_REJECTED_SKIP_REASON, SELF_TEST_HEALTHZ_PATH, SELF_TEST_PATH, SELF_TEST_SCHEMA_VERSION, SelfTestRequestSchema, } from "./self-test.js";
-export { resolveHealthCheckInputDateTokens } from "./self-test-input-tokens.js";
+export { resolveHealthCheckInputDateTokens, } from "./self-test-input-tokens.js";
 export { collectSelfTestSensitiveValues, redactSelfTestText, SELF_TEST_MAX_TEXT_LENGTH, SELF_TEST_REDACTED_PLACEHOLDER, } from "./self-test-redaction.js";
 export { DEFAULT_SELF_TEST_PORT, deriveSelfTestToken, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_ENV, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_PREVIOUS_ENV, PROVIDER_RUNTIME_SELF_TEST_PORT_ENV, resolveSelfTestMasterSecrets, verifySelfTestAuthorization, } from "./self-test-token.js";
 export { AuthFlowRequestSchema, AuthFlowSuccessResponseSchema, ConnectionModeSchema, ErrorEnvelopeSchema, OperationConnectionSchema, OperationErrorResponseSchema, OperationRequestSchema, OperationSuccessResponseSchema, } from "./types.js";

package/dist/server/self-test-input-tokens.d.ts

@@ -1 +1,2 @@
-export declare function resolveHealthCheckInputDateTokens(value: unknown, now?: Date): unknown;
+export type InputDateTokenCalendar = "KST" | "UTC";
+export declare function resolveHealthCheckInputDateTokens(value: unknown, now?: Date, calendar?: InputDateTokenCalendar): unknown;

package/dist/server/self-test-input-tokens.js

@@ -1,20 +1,20 @@
 /**
- * Relative-KST date token resolution for health-check case inputs, ported from
- * the monorepo health-monitor (`apps/health-monitor/src/lib/health-check-input.ts`)
- * so provider self-tests resolve durable probe inputs identically.
+ * Relative date-token resolution for health-check case inputs and fixture
+ * requests. The calendar defaults to KST; callers that need UTC must opt in
+ * explicitly so UTC and KST do not silently disagree from 15:00–23:59 UTC.
  *
- * Supported token: `+<days>d` or `+<days>d:YYYYMMDD` (1..365 days ahead, KST).
+ * Supported token: `+<days>d` or `+<days>d:YYYYMMDD` (1..365 days ahead).
  */
-const RELATIVE_KST_DATE_TOKEN = /^\+(\d{1,3})d(?::(YYYYMMDD))?$/i;
-function dateFromKstDaysAhead(daysAhead, now = new Date(), format = "YYYY-MM-DD") {
-    const kstNow = new Date(now.getTime() + 9 * 60 * 60 * 1000);
-    const date = new Date(Date.UTC(kstNow.getUTCFullYear(), kstNow.getUTCMonth(), kstNow.getUTCDate() + daysAhead));
+const RELATIVE_DATE_TOKEN = /^\+(\d{1,3})d(?::(YYYYMMDD))?$/i;
+function dateFromDaysAhead(daysAhead, now = new Date(), format = "YYYY-MM-DD", calendar = "KST") {
+    const calendarNow = new Date(now.getTime() + (calendar === "KST" ? 9 * 60 * 60 * 1000 : 0));
+    const date = new Date(Date.UTC(calendarNow.getUTCFullYear(), calendarNow.getUTCMonth(), calendarNow.getUTCDate() + daysAhead));
     const isoDate = date.toISOString().slice(0, 10);
     return format === "YYYYMMDD" ? isoDate.replace(/-/g, "") : isoDate;
 }
-export function resolveHealthCheckInputDateTokens(value, now = new Date()) {
+export function resolveHealthCheckInputDateTokens(value, now = new Date(), calendar = "KST") {
     if (typeof value === "string") {
-        const relative = value.match(RELATIVE_KST_DATE_TOKEN);
+        const relative = value.match(RELATIVE_DATE_TOKEN);
         if (!relative)
             return value;
         const daysAhead = Number(relative[1]);
@@ -22,16 +22,20 @@ export function resolveHealthCheckInputDateTokens(value, now = new Date()) {
             return value;
         }
         const format = relative[2]?.toUpperCase() === "YYYYMMDD" ? "YYYYMMDD" : "YYYY-MM-DD";
-        return dateFromKstDaysAhead(daysAhead, now, format);
+        return dateFromDaysAhead(daysAhead, now, format, calendar);
     }
     if (Array.isArray(value)) {
-        return value.map((entry) => resolveHealthCheckInputDateTokens(entry, now));
+        const resolved = value.map((entry) => resolveHealthCheckInputDateTokens(entry, now, calendar));
+        return resolved.some((entry, index) => entry !== value[index]) ? resolved : value;
     }
     if (value && typeof value === "object") {
-        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [
+        const resolved = Object.fromEntries(Object.entries(value).map(([key, entry]) => [
             key,
-            resolveHealthCheckInputDateTokens(entry, now),
+            resolveHealthCheckInputDateTokens(entry, now, calendar),
         ]));
+        return Object.entries(resolved).some(([key, entry]) => entry !== Reflect.get(value, key))
+            ? resolved
+            : value;
     }
     return value;
 }

package/dist/stream-evidence.d.ts

@@ -0,0 +1,74 @@
+import { type JsonValue } from "./contract-json.js";
+import type { HttpStreamResponse } from "./types.js";
+export declare const STREAM_PREVIEW_BYTES = 4096;
+export declare const STREAM_FINALIZE_TIMEOUT_MS = 30000;
+declare const STREAM_EVIDENCE_HEADER_NAMES: readonly ["content-disposition", "content-length", "content-type"];
+type StreamEvidenceHeaderName = (typeof STREAM_EVIDENCE_HEADER_NAMES)[number];
+export type StreamEvidenceHeaders = Partial<Record<StreamEvidenceHeaderName, string>>;
+export interface StreamEvidenceRequest {
+    ordinal: number;
+    method: string;
+    path: string;
+}
+declare const STREAM_EVIDENCE_REDACTION_REASONS: readonly ["high-entropy-token", "malformed-json", "pem-private-key", "sanitized-preview-too-large", "sanitizer-output-invalid", "sensitive-delimited-column", "textual-xml", "truncated-form", "truncated-json", "undecodable-text"];
+export type StreamEvidenceRedactionReason = (typeof STREAM_EVIDENCE_REDACTION_REASONS)[number];
+export interface StreamEvidenceRecord {
+    __apifuse_stream__: true;
+    status: number;
+    ok: boolean;
+    headers: StreamEvidenceHeaders;
+    body_sha256: string;
+    body_bytes: number;
+    body_preview_base64: string;
+    request?: StreamEvidenceRequest;
+    preview_sanitized?: true;
+    preview_redaction_reason?: StreamEvidenceRedactionReason;
+}
+export type StreamEvidenceReplayResponse = HttpStreamResponse & {
+    evidence_only: true;
+    body_sha256: string;
+    body_bytes: number;
+    preview_sanitized?: true;
+    preview_redaction_reason?: StreamEvidenceRedactionReason;
+};
+export interface StreamEvidenceCapture {
+    response: HttpStreamResponse;
+    getEvidence(): Promise<StreamEvidenceRecord>;
+}
+export type StreamCaptureGroupItem = {
+    kind: "stream";
+    evidence: StreamEvidenceRecord;
+} | {
+    kind: "response";
+    value: JsonValue;
+};
+export interface StreamCaptureGroup {
+    items: StreamCaptureGroupItem[];
+}
+export interface StreamCaptureEnvelope {
+    __apifuse_capture__: true;
+    items: StreamCaptureGroupItem[];
+}
+export type StreamEvidenceCaptureOptions = {
+    requestUrl: string;
+    sanitizeFixture?: (value: JsonValue) => JsonValue;
+    request?: StreamEvidenceRequest;
+    finalizeTimeoutMs?: number;
+};
+export declare function parseStreamEvidenceRecord(value: unknown): StreamEvidenceRecord;
+export declare function isStreamEvidenceRecord(value: unknown): value is StreamEvidenceRecord;
+export declare function findStreamEvidenceRecord(value: unknown): StreamEvidenceRecord | undefined;
+/**
+ * Selects every stream captured by the latest recording invocation, in stream call order.
+ * Evidence without request ordinals uses the legacy latest-record-only behavior.
+ */
+export declare function findStreamEvidenceRecords(value: unknown): StreamEvidenceRecord[];
+/** Returns a tagged latest mixed response group used by evidence-only snapshot replay. */
+export declare function findStreamCaptureGroup(value: unknown): StreamCaptureGroup | undefined;
+/** Creates a discriminated invocation envelope so ordinary arrays cannot mimic capture timelines. */
+export declare function createStreamCaptureEnvelope(items: StreamCaptureGroupItem[]): StreamCaptureEnvelope;
+export declare function isStreamEvidenceReplayResponse(response: HttpStreamResponse): response is StreamEvidenceReplayResponse;
+export declare function captureStreamEvidence(response: HttpStreamResponse, options: StreamEvidenceCaptureOptions): StreamEvidenceCapture;
+export declare function replayStreamEvidence(evidence: StreamEvidenceRecord): StreamEvidenceReplayResponse;
+export declare function hasStreamEvidenceMarker(value: unknown): boolean;
+export {};