@apifuse/provider-sdk 2.2.0-beta.59 → 2.2.0-beta.61

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

@@ -58,6 +58,8 @@ export declare function createCeremonyEgressLeaseRuntime(options: {
     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;

package/dist/runtime/egress-lease.js

@@ -1,3 +1,4 @@
+import { readDiagnosticEnv } from "./diagnostic-env.js";
 import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
 import { SDKError } from "../errors.js";
 /**
@@ -156,7 +157,7 @@ export function createCeremonyEgressLeaseRuntime(options) {
         flowId: options.flowId,
         affinityKey: options.affinityKey,
     };
-    const key = environment[APIFUSE__ENGINE__CEREMONY_LEASE_KEY]?.trim();
+    const key = readDiagnosticEnv(APIFUSE__ENGINE__CEREMONY_LEASE_KEY, environment)?.trim();
     if (!key) {
         throw new SDKError("The engine ceremony egress lease key is not configured", {
             code: "EGRESS_LEASE_KEY_MISSING",
@@ -184,6 +185,7 @@ export function createCeremonyEgressLeaseRuntime(options) {
     };
     const dropExpiredBinding = () => payload !== undefined && now() >= payload.expiresAtMs ? dropBinding() : false;
     if (options.handle !== undefined) {
+        options.onHandle?.(options.handle);
         // Scope mismatch fails GCM authentication because scope is AAD; there is
         // deliberately no post-decrypt scope comparison fallback.
         payload = decodeHandle(options.handle, key, scope);
@@ -225,6 +227,7 @@ export function createCeremonyEgressLeaseRuntime(options) {
                 expiresAtMs: mintedAtMs + binding.lifetimeMinutes * 60_000,
             };
             currentHandle = encodeHandle(payload, key, scope);
+            options.onHandle?.(currentHandle);
         },
         handle() {
             return currentHandle;

package/dist/runtime/env.js

@@ -1,3 +1,4 @@
+import { readDiagnosticEnv } from "./diagnostic-env.js";
 import { isEngineOwnedEnvName } from "../engine.js";
 /**
  * A mixed-case spelling of an engine-owned name is an alias: on Windows it resolves to the
@@ -16,7 +17,7 @@ export function createEnvContext(allowedKeys) {
             if (isEngineOwnedEnvAlias(key)) {
                 return undefined;
             }
-            return process.env[key];
+            return readDiagnosticEnv(key);
         },
     };
 }

package/dist/runtime/handle-wordlist.d.ts

@@ -0,0 +1,43 @@
+export declare const HANDLE_WORDLIST_SIZE = 1296;
+export declare const HANDLE_WORD_ENTROPY_BITS: number;
+/**
+ * Bound handles live under `state.forConnection(connectionId)`: another
+ * connection cannot address them at all, so no guessing analysis applies. The
+ * only requirement is uniqueness among live handles of one connection
+ * (1,296^2 = 1.68M keys, CAS-if-absent with retries), which two words satisfy.
+ */
+export declare const BOUND_HANDLE_WORD_COUNT = 2;
+/** Public handles are addressable by anyone; ADR 0006 §2 guessing numbers apply. */
+export declare const PUBLIC_HANDLE_WORD_COUNT = 4;
+/** Used when a public kind declares `strength: "high"` or its ttl exceeds one hour. */
+export declare const HIGH_PUBLIC_HANDLE_WORD_COUNT = 5;
+export declare const PUBLIC_HANDLE_ENTROPY_BITS: number;
+export declare const HIGH_PUBLIC_HANDLE_ENTROPY_BITS: number;
+export declare const EFF_SHORT_WORDLIST_2: readonly string[];
+/**
+ * Words the runtime may issue. The handle grammar joins words with `-`, so the
+ * one hyphenated official entry (`yo-yo`) would fuse with the separator and is
+ * never issued. The official list itself stays embedded unchanged.
+ */
+export declare const ISSUABLE_HANDLE_WORDS: readonly string[];
+export declare function handleWordAt(index: number): string;
+export declare function isHandleWord(value: string): boolean;
+/**
+ * Symmetric-deletion index (SymSpell, max distance 1). Two strings at
+ * Levenshtein distance <= 1 always share a form reachable by deleting at most
+ * one character from each side, so a lookup of the query and its one-deletion
+ * variants yields every candidate; a real distance check then removes the false
+ * positives (e.g. transpositions). ~10k entries, O(len) per lookup.
+ */
+/** Shortest and longest words in the list (3 and 10 for the official list). */
+export declare const MIN_HANDLE_WORD_LENGTH: number;
+export declare const MAX_HANDLE_WORD_LENGTH: number;
+/**
+ * Resolves one handle segment to a wordlist entry: the exact word, or the
+ * unique word at edit distance <= `maxDistance`. Returns null when no word or
+ * more than one word qualifies. The official list has pairwise edit distance
+ * >= 3, so at distance 1 every non-null answer is unique; the uniqueness check
+ * is kept as a guard so a wordlist change cannot silently make normalization
+ * map one input onto two different canonical handles.
+ */
+export declare function findHandleWordWithinDistance(segment: string, maxDistance: 1): string | null;