@apifuse/provider-sdk 2.2.0-beta.58 → 2.2.0-beta.60

package/dist/runtime/diagnostic-redactor.js

@@ -0,0 +1,569 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { allSensitiveValueVariants, normalizePercentEscapes, REDACTED_QUERY_VALUE, } from "./request-options.js";
+export const REDACTION_FAILED = "[REDACTION_FAILED]";
+// No supported credential source needs 1–3 character secrets. Registering these
+// common tokens damages unrelated IDs and diagnostics even with token boundaries.
+// Apply the same floor to static, fallback and request inventories (as self-test does).
+const MINIMUM_REGISTERED_VALUE_LENGTH = 4;
+/** Observer failures must never return the original diagnostic, including via ?? fallbacks. */
+export function redactDiagnosticText(text, redact) {
+    try {
+        const result = redact ? redact(text) : text;
+        return typeof result === "string" ? result : REDACTION_FAILED;
+    }
+    catch {
+        return REDACTION_FAILED;
+    }
+}
+function node() {
+    return { next: new Map() };
+}
+function compile(variants) {
+    const matcher = {
+        exact: node(),
+        folded: node(),
+        hasFolded: false,
+        // Only long values participate in encoded matching. Unreserved ASCII is
+        // percent-encodable too (%6f for o); encodeURIComponent(value) === value
+        // does NOT prove that residual escapes cannot conceal that credential.
+        canMatchPercentEncoded: variants.some((variant) => variant.caseInsensitive),
+        size: variants.length,
+        minimumLength: variants.reduce((minimum, variant) => Math.min(minimum, variant.value.length), Infinity),
+        cache: new Map(),
+    };
+    if (variants.some((variant) => !variant.caseInsensitive))
+        matcher.encoded = compile(variants.filter((variant) => variant.caseInsensitive));
+    // A few request credentials are cheaper as native literal searches; large
+    // process-static inventories use tries to avoid per-needle scans.
+    if (variants.length <= 16) {
+        matcher.needles = variants.map((variant) => ({
+            ...variant,
+            value: variant.caseInsensitive ? variant.value.toLowerCase() : variant.value,
+        }));
+        matcher.hasFolded = variants.some((variant) => variant.caseInsensitive);
+        return matcher;
+    }
+    for (const variant of variants) {
+        let current = variant.caseInsensitive ? matcher.folded : matcher.exact;
+        if (variant.caseInsensitive)
+            matcher.hasFolded = true;
+        const value = variant.caseInsensitive ? variant.value.toLowerCase() : variant.value;
+        for (let index = 0; index < value.length; index++) {
+            const character = value[index];
+            let child = current.next.get(character);
+            if (!child) {
+                child = node();
+                current.next.set(character, child);
+            }
+            current = child;
+        }
+        current.boundary =
+            current.boundary === undefined
+                ? variant.requiresTokenBoundary
+                : current.boundary && variant.requiresTokenBoundary;
+    }
+    return matcher;
+}
+const compiledValues = new WeakMap();
+export function compileDiagnosticSensitiveValues(values) {
+    const handle = Object.freeze({
+        kind: "compiled-diagnostic-sensitive-values",
+    });
+    const registered = values.filter((value) => value.length >= MINIMUM_REGISTERED_VALUE_LENGTH);
+    const variants = allSensitiveValueVariants(registered);
+    const primary = compile(variants), check = compile(variants);
+    compiledValues.set(handle, {
+        primary,
+        check,
+        criticalPrimary: primary.encoded ?? primary,
+        criticalCheck: check.encoded ?? check,
+        values: new Set(registered),
+    });
+    return handle;
+}
+// Outside-context reads are process lifetime data, bounded like request harvesting.
+const PROCESS_VALUE_LIMIT = 1024;
+const PROCESS_BYTE_LIMIT = 64 * 1024;
+function createDiagnosticFallback() {
+    return {
+        values: new Set(),
+        bytes: 0,
+        suppressed: false,
+        version: 0,
+        compiledVersion: -1,
+        compiled: undefined,
+    };
+}
+const processFallback = createDiagnosticFallback();
+const fallbackScopes = new AsyncLocalStorage();
+const processCompositions = new WeakMap();
+/**
+ * Give an independent runtime/configuration evaluation its own fallback lifetime.
+ * Apps created inside the scope retain that inventory, including across awaits and
+ * after the callback returns. Ordinary startup/CLI reads keep the process lifetime.
+ * This also lets test harnesses isolate synthetic env reads without clearing live
+ * apps' credentials or weakening registration, matching, or exhaustion policies.
+ */
+export function withDiagnosticFallbackScope(fn) {
+    return fallbackScopes.run(createDiagnosticFallback(), fn);
+}
+/** Re-enter the app's existing lifetime, including for detached request callbacks. */
+export function withAppDiagnosticFallback(staticValues, fn) {
+    return fallbackScopes.run(processCompositions.get(staticValues) ?? currentDiagnosticFallback(), fn);
+}
+function currentDiagnosticFallback() {
+    return fallbackScopes.getStore() ?? processFallback;
+}
+export function suppressProcessDiagnosticValues() {
+    const fallback = currentDiagnosticFallback();
+    if (fallback.suppressed)
+        return;
+    fallback.suppressed = true;
+    console.warn("[apifuse] diagnostic redaction failed closed; reason=static_registry_limit; limit=1024_entries/65536_bytes");
+}
+export function registerProcessDiagnosticValues(values) {
+    const fallback = currentDiagnosticFallback();
+    if (fallback.suppressed)
+        return;
+    for (const value of values) {
+        if (value.length < MINIMUM_REGISTERED_VALUE_LENGTH || fallback.values.has(value))
+            continue;
+        const bytes = Buffer.byteLength(value);
+        if (fallback.values.size >= PROCESS_VALUE_LIMIT ||
+            fallback.bytes + bytes > PROCESS_BYTE_LIMIT) {
+            suppressProcessDiagnosticValues();
+            return;
+        }
+        fallback.values.add(value);
+        fallback.bytes += bytes;
+        fallback.version++;
+    }
+}
+/** The app's static inventory and the shared outside-context fallback form one static part. */
+export function compileProcessDiagnosticSensitiveValues(values) {
+    const handle = compileDiagnosticSensitiveValues(values);
+    processCompositions.set(handle, currentDiagnosticFallback());
+    return handle;
+}
+function isTokenCharacter(value) {
+    return value !== undefined && /[\p{L}\p{N}]/u.test(value);
+}
+function matchLength(root, comparable, original, start) {
+    let current = root;
+    let length = 0;
+    for (let index = start; index < comparable.length; index++) {
+        const child = current.next.get(comparable[index]);
+        if (!child)
+            break;
+        current = child;
+        if (current.boundary !== undefined &&
+            (!current.boundary ||
+                (!isTokenCharacter(original[start - 1]) && !isTokenCharacter(original[index + 1])))) {
+            length = index - start + 1;
+        }
+    }
+    return length;
+}
+function replaceNeedles(text, matcher, checkOnly) {
+    const comparable = text.includes("%") ? normalizePercentEscapes(text) : text;
+    const folded = matcher.hasFolded ? comparable.toLowerCase() : comparable;
+    let cursor = 0;
+    let output = "";
+    while (cursor < text.length) {
+        let first = text.length;
+        let length = 0;
+        for (const variant of matcher.needles ?? []) {
+            const source = variant.caseInsensitive ? folded : text;
+            let index = source.indexOf(variant.value, cursor);
+            while (index !== -1) {
+                const end = index + variant.value.length;
+                const markerStart = source.lastIndexOf("[", index);
+                const withinMarker = markerStart !== -1 && index < markerStart + markerLength(comparable, markerStart);
+                if (!withinMarker &&
+                    (!variant.requiresTokenBoundary ||
+                        (!isTokenCharacter(source[index - 1]) && !isTokenCharacter(source[end]))))
+                    break;
+                index = source.indexOf(variant.value, index + 1);
+            }
+            if (index === -1)
+                continue;
+            if (checkOnly || (variant.caseInsensitive && folded.length !== text.length))
+                return REDACTED_QUERY_VALUE;
+            if (index < first || (index === first && variant.value.length > length)) {
+                first = index;
+                length = variant.value.length;
+            }
+        }
+        if (!length)
+            break;
+        output += text.slice(cursor, first) + REDACTED_QUERY_VALUE;
+        cursor = first + length;
+    }
+    return cursor ? output + text.slice(cursor) : text;
+}
+/** Literal tries have no secret-built regular expressions and no per-needle no-match scans. */
+function replaceMatches(text, matchers, checkOnly = false) {
+    if (matchers.length === 1 && matchers[0].needles)
+        return replaceNeedles(text, matchers[0], checkOnly);
+    const comparable = text.includes("%") ? normalizePercentEscapes(text) : text;
+    const folded = matchers.some((matcher) => matcher.hasFolded)
+        ? comparable.toLowerCase()
+        : comparable;
+    // Unicode case folding can change offsets. Suppress the field on a folded match.
+    if (folded.length !== comparable.length) {
+        for (const matcher of matchers) {
+            for (let index = 0; index < folded.length; index++) {
+                if (matchLength(matcher.folded, folded, folded, index))
+                    return REDACTED_QUERY_VALUE;
+            }
+        }
+    }
+    let cursor = 0;
+    let output = "";
+    for (let index = 0; index < text.length; index++) {
+        // Sentinels are emitted constants, not evidence of a residual credential.
+        const marker = markerLength(text, index);
+        if (marker) {
+            index += marker - 1;
+            continue;
+        }
+        let length = 0;
+        for (const matcher of matchers) {
+            length = Math.max(length, matchLength(matcher.exact, text, text, index));
+            if (matcher.hasFolded && folded.length === comparable.length) {
+                length = Math.max(length, matchLength(matcher.folded, folded, text, index));
+            }
+        }
+        if (!length)
+            continue;
+        if (checkOnly)
+            return REDACTED_QUERY_VALUE;
+        output += text.slice(cursor, index) + REDACTED_QUERY_VALUE;
+        cursor = index + length;
+        index = cursor - 1;
+    }
+    return cursor === 0 ? text : output + text.slice(cursor);
+}
+function decodePercent(text) {
+    try {
+        return decodeURIComponent(text);
+    }
+    catch {
+        // An unrelated malformed escape must not hide valid encoded credential text.
+        return text.replace(/(?:%[\da-f]{2})+/gi, (part) => {
+            try {
+                return decodeURIComponent(part);
+            }
+            catch {
+                return part.replace(/%([\da-f]{2})/gi, (encodedByte, hex) => {
+                    const byte = Number.parseInt(hex, 16);
+                    return byte < 128 ? String.fromCharCode(byte) : encodedByte;
+                });
+            }
+        });
+    }
+}
+function applyMatcher(text, matcher) {
+    if (!matcher.size)
+        return text;
+    // ASCII cannot grow under NFC/case folding; without escapes, a shorter field
+    // cannot contain any needle. Keep decoding and Unicode checks on the full path.
+    if (text.length < matcher.minimumLength && !text.includes("%") && !/[\u0080-\uffff]/.test(text))
+        return text;
+    const cached = matcher.cache.get(text);
+    if (cached !== undefined)
+        return cached;
+    const matchers = [matcher];
+    const direct = replaceMatches(text, matchers);
+    let result = direct;
+    let normalized = direct;
+    for (let round = 0; round < 3 && normalized.includes("%"); round++) {
+        const decoded = decodePercent(normalized);
+        if (decoded === normalized)
+            break;
+        normalized = decoded;
+        if (replaceMatches(normalized, [matcher.encoded ?? matcher], true) !== normalized) {
+            result = REDACTED_QUERY_VALUE;
+        }
+    }
+    // A residual escape is unresolved after the fixed work budget: emit less,
+    // if this nonempty registry can match percent-encoded credentials, even when
+    // another representation matched. Both independent roles use this.
+    if (matcher.canMatchPercentEncoded && /%[\da-f]{2}/i.test(normalized))
+        result = REDACTION_FAILED;
+    const nfc = normalized.normalize("NFC");
+    if (result !== REDACTION_FAILED &&
+        nfc !== normalized &&
+        replaceMatches(nfc, [matcher.encoded ?? matcher], true) !== nfc)
+        result = REDACTED_QUERY_VALUE;
+    // Matchers are immutable; additions compile a new request matcher. Independent
+    // request-local caches reuse results across repeated span/resource exports. Bound
+    // entry count and input size; process-static lookup data never caches request text.
+    if (text.length <= 4096) {
+        if (matcher.cache.size >= 256)
+            matcher.cache.clear();
+        matcher.cache.set(text, result);
+    }
+    return result;
+}
+function applyMatchers(text, matchers) {
+    let result = text;
+    for (const matcher of matchers) {
+        const candidate = applyMatcher(text, matcher);
+        if (candidate === text)
+            continue;
+        // Static and request secrets may overlap. Scan original text independently
+        // so an earlier replacement cannot hide the rest of a longer credential.
+        if (result !== text && result !== candidate)
+            return REDACTED_QUERY_VALUE;
+        result = candidate;
+    }
+    return result;
+}
+/** One small mutable registry per request, composed with precompiled process-static values. */
+export function createDiagnosticRedactor(values = [], staticValues) {
+    const compiled = staticValues ? compiledValues.get(staticValues) : undefined;
+    // Share immutable lookup data only. Raw diagnostic cache keys die with this scope.
+    const requestMatcher = (matcher) => ({ ...matcher, cache: new Map() });
+    const staticPrimary = compiled?.primary.size ? requestMatcher(compiled.primary) : undefined;
+    const staticCheck = compiled?.check.size ? requestMatcher(compiled.check) : undefined;
+    const staticCriticalPrimary = compiled?.criticalPrimary.size
+        ? compiled.criticalPrimary === compiled.primary
+            ? staticPrimary
+            : requestMatcher(compiled.criticalPrimary)
+        : undefined;
+    const staticCriticalCheck = compiled?.criticalCheck.size
+        ? compiled.criticalCheck === compiled.check
+            ? staticCheck
+            : requestMatcher(compiled.criticalCheck)
+        : undefined;
+    const known = new Set();
+    const fallback = staticValues === undefined ? undefined : processCompositions.get(staticValues);
+    const has = (value) => known.has(value) ||
+        compiled?.values.has(value) === true ||
+        fallback?.values.has(value) === true;
+    let seenProcessVersion = -1;
+    let fallbackPrimary = [];
+    let fallbackCheck = [];
+    let fallbackCriticalPrimary = [];
+    let fallbackCriticalCheck = [];
+    let requestPrimary;
+    let requestCheck;
+    let suppressed = false;
+    let primary = staticPrimary ? [staticPrimary] : [];
+    let check = staticCheck ? [staticCheck] : [];
+    let criticalPrimary = staticCriticalPrimary ? [staticCriticalPrimary] : [];
+    let criticalCheck = staticCriticalCheck ? [staticCriticalCheck] : [];
+    const variants = [];
+    let uncompiled = [];
+    const add = (incoming) => {
+        for (const value of incoming) {
+            if (value.length < MINIMUM_REGISTERED_VALUE_LENGTH || has(value))
+                continue;
+            known.add(value);
+            uncompiled.push(value);
+        }
+    };
+    const ensureCompiled = () => {
+        const processChanged = fallback !== undefined && seenProcessVersion !== fallback.version;
+        if (!uncompiled.length && !processChanged)
+            return;
+        if (processChanged) {
+            if (fallback.compiledVersion !== fallback.version) {
+                fallback.compiled = compileDiagnosticSensitiveValues([...fallback.values]);
+                fallback.compiledVersion = fallback.version;
+            }
+            const compiledFallback = fallback.compiled && compiledValues.get(fallback.compiled);
+            fallbackPrimary = compiledFallback?.primary.size
+                ? [requestMatcher(compiledFallback.primary)]
+                : [];
+            fallbackCheck = compiledFallback?.check.size ? [requestMatcher(compiledFallback.check)] : [];
+            fallbackCriticalPrimary = compiledFallback?.criticalPrimary.size
+                ? [requestMatcher(compiledFallback.criticalPrimary)]
+                : [];
+            fallbackCriticalCheck = compiledFallback?.criticalCheck.size
+                ? [requestMatcher(compiledFallback.criticalCheck)]
+                : [];
+            seenProcessVersion = fallback.version;
+        }
+        if (uncompiled.length) {
+            // Generate each value's variants once, lazily on the first actual match.
+            variants.push(...allSensitiveValueVariants(uncompiled));
+            uncompiled = [];
+            requestPrimary = compile(variants);
+            requestCheck = compile(variants);
+        }
+        primary = [
+            ...(staticPrimary ? [staticPrimary] : []),
+            ...fallbackPrimary,
+            ...(requestPrimary ? [requestPrimary] : []),
+        ];
+        check = [
+            ...(staticCheck ? [staticCheck] : []),
+            ...fallbackCheck,
+            ...(requestCheck ? [requestCheck] : []),
+        ];
+        criticalPrimary = [
+            ...(staticCriticalPrimary ? [staticCriticalPrimary] : []),
+            ...fallbackCriticalPrimary,
+            ...(requestPrimary ? [requestPrimary.encoded ?? requestPrimary] : []),
+        ];
+        criticalCheck = [
+            ...(staticCriticalCheck ? [staticCriticalCheck] : []),
+            ...fallbackCriticalCheck,
+            ...(requestCheck ? [requestCheck.encoded ?? requestCheck] : []),
+        ];
+    };
+    add(values);
+    const protect = (callback, critical = false, freeText = !critical) => (text) => {
+        if (text === REDACTED_QUERY_VALUE || text === REDACTION_FAILED)
+            return text;
+        if ((suppressed || fallback?.suppressed) && freeText)
+            return REDACTION_FAILED;
+        ensureCompiled();
+        const result = redactDiagnosticText(text, callback);
+        ensureCompiled(); // A replaced callback may register a value during the call.
+        if ((suppressed || fallback?.suppressed) && freeText)
+            return REDACTION_FAILED;
+        // This private matcher is a separate object from the callback's matcher,
+        // survives callback replacement, and sees additions made after trace creation.
+        return applyMatchers(result, critical ? criticalCheck : check) === result
+            ? result
+            : REDACTION_FAILED;
+    };
+    let safeRedact = protect((text) => applyMatchers(text, primary));
+    let safeCritical = protect((text) => applyMatchers(text, criticalPrimary), true);
+    let safeStructured = protect((text) => applyMatchers(text, primary), false, false);
+    const critical = (text) => safeCritical(text);
+    const structured = (text) => safeStructured(text);
+    const isSuppressed = () => suppressed || fallback?.suppressed === true;
+    bindCriticalDiagnosticRedactor(safeRedact, critical, structured, isSuppressed);
+    return {
+        add,
+        has,
+        redactCritical: critical,
+        redactStructured: structured,
+        get suppressed() {
+            return isSuppressed();
+        },
+        suppress() {
+            suppressed = true;
+        },
+        get redact() {
+            return safeRedact;
+        },
+        set redact(callback) {
+            safeRedact = protect(callback);
+            safeCritical = protect(callback, true);
+            safeStructured = protect(callback, false, false);
+            bindCriticalDiagnosticRedactor(safeRedact, critical, structured, isSuppressed);
+        },
+    };
+}
+const requestRegistries = new WeakMap();
+/** Internal binding; neither the registry nor its values enter provider-facing context types. */
+export function bindDiagnosticSensitiveRegistry(trace, registry) {
+    requestRegistries.set(trace, registry);
+}
+export function registerDiagnosticSensitiveValues(trace, values) {
+    requestRegistries.get(trace)?.add(values);
+}
+// Policy metadata is internal: public callbacks remain backward-compatible unary functions.
+const criticalRedactors = new WeakMap();
+const structuredRedactors = new WeakMap();
+const redactionSuppression = new WeakMap();
+export function bindCriticalDiagnosticRedactor(redact, critical, structured, isSuppressed) {
+    criticalRedactors.set(redact, critical);
+    if (structured)
+        structuredRedactors.set(redact, structured);
+    if (isSuppressed)
+        redactionSuppression.set(redact, isSuppressed);
+}
+export function isDiagnosticRedactionSuppressed(redact) {
+    return redact ? redactionSuppression.get(redact)?.() === true : false;
+}
+/** Typed values and keys still match known credentials, but never blanket suppression. */
+export function diagnosticStructuredRedactor(redact) {
+    return redact ? (structuredRedactors.get(redact) ?? redact) : undefined;
+}
+export function redactDiagnosticAttributeKey(key, redact) {
+    return redactDiagnosticText(key, diagnosticStructuredRedactor(diagnosticAttributeRedactor(key, redact)));
+}
+export function redactCriticalDiagnosticText(text, redact) {
+    return redactDiagnosticText(text, redact ? (criticalRedactors.get(redact) ?? redact) : undefined);
+}
+export function diagnosticAttributeRedactor(key, redact) {
+    if (CLOSED_ENUM_ATTRIBUTE_KEYS.has(key))
+        return diagnosticStructuredRedactor(redact);
+    return CRITICAL_ATTRIBUTE_KEYS.has(key) && redact
+        ? (criticalRedactors.get(redact) ?? redact)
+        : redact;
+}
+// Structured debugging contracts use only >=8-character values. Other attributes are free text.
+const CRITICAL_ATTRIBUTE_KEYS = new Set([
+    "request_id",
+    "requestId",
+    "trace_id",
+    "traceId",
+    "span_id",
+    "spanId",
+    "route",
+    "operation_id",
+    "operation",
+    "http.status_code",
+]);
+// SDK-owned closed enums are contracts, like typed numbers and booleans. This
+// exempts only exhaustion suppression; registered credentials still match.
+const CLOSED_ENUM_ATTRIBUTE_KEYS = new Set([
+    "outcome",
+    "code",
+    "errorClass",
+    "phase",
+    "cacheStatus",
+    "identitySource",
+    "taxonomy",
+    "taxonomyVersion",
+]);
+// Bigints normalize to strings for OTLP. Carry their type policy through internal
+// detached copies without treating arbitrary numeric-looking free text as typed.
+const bigintAttributes = new WeakMap();
+export function isDiagnosticBigintAttribute(attributes, key) {
+    return bigintAttributes.get(attributes)?.has(key) === true;
+}
+export function copyDiagnosticAttributeTypes(source, target) {
+    const keys = Object.keys(source).filter((key) => (typeof source[key] === "bigint" || isDiagnosticBigintAttribute(source, key)) &&
+        String(source[key]) === target[key]);
+    if (keys.length)
+        bigintAttributes.set(target, new Set(keys));
+    return target;
+}
+/** Reserve existing keys so independently redacted names never drop an attribute. */
+export function redactedKeyAllocator(keys) {
+    // Snapshot the inventory now, but allocate its lookup only if a key changes.
+    const inventory = [...keys];
+    let reserved;
+    let sequence = 0;
+    return () => {
+        reserved ??= new Set(inventory);
+        let key;
+        do {
+            key = `[REDACTED#${++sequence}]`;
+        } while (reserved.has(key));
+        reserved.add(key);
+        return key;
+    };
+}
+export function isRedactedKey(key) {
+    return /^\[REDACTED#\d+\]$/.test(key);
+}
+function markerLength(text, index) {
+    if (text[index] !== "[")
+        return 0;
+    if (text.startsWith(REDACTED_QUERY_VALUE, index))
+        return REDACTED_QUERY_VALUE.length;
+    if (text.startsWith(REDACTION_FAILED, index))
+        return REDACTION_FAILED.length;
+    if (text.startsWith("[REDACTED#", index))
+        return /^\[REDACTED#\d+\]/.exec(text.slice(index))?.[0].length ?? 0;
+    return 0;
+}

package/dist/runtime/egress-lease.d.ts

@@ -0,0 +1,65 @@
+import type { ProxyVendorName } from "../config/loader.js";
+/**
+ * AES-256-GCM key for the engine ceremony egress lease handle (ADR-0010 v1.1).
+ * Engine host only: the `APIFUSE__ENGINE__` family is rejected from provider
+ * secrets and filtered from provider env projections. Supply at least 32 random
+ * bytes (for example `openssl rand -base64 32`). Rotating the key fails
+ * verification of every outstanding handle (`EGRESS_LEASE_INVALID`, 409): the
+ * affected ceremonies restart; they do not expire.
+ */
+export declare const APIFUSE__ENGINE__CEREMONY_LEASE_KEY = "APIFUSE__ENGINE__CEREMONY_LEASE_KEY";
+/** Internal option key shared only by the server assembler and stealth runtime. */
+export declare const ENGINE_CEREMONY_EGRESS_LEASE: unique symbol;
+export type CeremonyEgressBinding = {
+    readonly vendor: ProxyVendorName;
+    readonly proxyUrl: string;
+    readonly poolIndex: number;
+    readonly affinityKey: string;
+    readonly refreshEpoch: number;
+    /**
+     * Vendor session lifetime the endpoint was allocated for (`proxy.session.lifetimeMinutes`,
+     * Smartproxy `life`, NodeMaven SID window). It is the upper bound of the lease, counted
+     * from the mint (the first successful attempt), so a Smartproxy lease can outlive the
+     * vendor session by the extraction-cache reuse window; expiry then drops and rebinds.
+     * The bound is not a vendor guarantee (ADR-0010: a raw Smartproxy endpoint is not a hard
+     * lease): the stealth runtime releases the binding as soon as the endpoint fails at the
+     * transport, so a dead endpoint is left before the lifetime elapses.
+     */
+    readonly lifetimeMinutes: number;
+};
+export type CeremonyEgressLeaseRuntime = {
+    /** Exact egress bound to this ceremony; undefined until the first successful attempt binds one. */
+    readonly binding: CeremonyEgressBinding | undefined;
+    /**
+     * Drops the binding once its vendor session lifetime has elapsed so the next attempt
+     * selects and binds a fresh endpoint. Returns true when a binding was dropped: the
+     * caller must also discard challenge state that was only valid for that endpoint.
+     */
+    dropExpiredBinding(): boolean;
+    /**
+     * Drops the binding unconditionally; the stealth runtime calls this when the bound
+     * endpoint fails at the transport. Same return and caller obligation as
+     * `dropExpiredBinding`.
+     */
+    dropBinding(): boolean;
+    /**
+     * Number of bindings dropped so far (expiry or release). Every stealth session created
+     * from one client shares the lease; a session compares this to what it last observed to
+     * retire endpoint-bound challenge state and replay records after another session moved
+     * the ceremony.
+     */
+    readonly generation: number;
+    bind(binding: CeremonyEgressBinding): void;
+    handle(): string | undefined;
+};
+export declare function createCeremonyEgressLeaseRuntime(options: {
+    readonly tenantId?: string;
+    readonly providerId: string;
+    readonly flowId: string;
+    readonly affinityKey: string;
+    readonly handle?: string;
+    /** Server-only registration before a handle can reach request diagnostics. */
+    readonly onHandle?: (handle: string) => void;
+    readonly environment?: Readonly<Record<string, string | undefined>>;
+    readonly now?: () => number;
+}): CeremonyEgressLeaseRuntime;