@latchway/react-native 0.0.0-bootstrap.0 → 1.1.0

package/lib/client.js

@@ -0,0 +1,939 @@
+import { LatchwayError } from "@latchway/client";
+import { ReadableStream as PonyfillReadableStream } from "web-streams-polyfill";
+import { encodeIOSComponentDescriptor, encodeIOSComponentDescriptors } from "./config.js";
+import { acquire } from "./coordinator.js";
+import { parseComponentDiagnostics } from "./component-client.js";
+import { abortError, fromNativeError } from "./errors.js";
+import { assertNoCredentialFields } from "./native-output.js";
+import { CONTRACT_VERSION, PROTOCOL_VERSION, SDK_VERSION } from "./version.js";
+const MAXIMUM_REQUEST_BODY_BYTES = 8 * 1024 * 1024;
+const MAXIMUM_NATIVE_REQUEST_BYTES = 12 * 1024 * 1024;
+const MAXIMUM_RESPONSE_CHUNK_BYTES = 32 * 1024;
+const MAXIMUM_HEADERS = 128;
+const MAXIMUM_HEADER_BYTES = 128 * 1024;
+const allowedDataPlanePaths = new Set([
+    "/v1/responses",
+    "/v1/chat/completions",
+    "/v1/embeddings",
+    "/v1/messages",
+]);
+const opaqueDataPlaneMethods = new Set(["GET", "POST", "PUT", "PATCH", "DELETE"]);
+const forbiddenCredentialHeaders = new Set([
+    "authorization",
+    "proxy-authorization",
+    "api-key",
+    "api_key",
+    "apikey",
+    "x-api-key",
+    "openai-api-key",
+    "openai_api_key",
+    "x-openai-api-key",
+    "anthropic-api-key",
+    "anthropic_api_key",
+    "x-goog-api-key",
+    "x-goog_api_key",
+    "access_token",
+    "auth_token",
+    "x-auth-token",
+    "cookie",
+    "connection",
+    "content-length",
+    "expect",
+    "host",
+    "key",
+    "proxy-connection",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "token",
+    "upgrade",
+    "x-amz-credential",
+    "x-amz-security-token",
+    "x-amz-signature",
+    "x-goog-credential",
+    "x-goog-signature",
+    "dpop",
+    "dpop-nonce",
+    "x-latchway-feature",
+    "x-latchway-framework",
+    "x-latchway-framework-version",
+    "x-latchway-protocol-version",
+    "x-latchway-request-id",
+    "x-latchway-sdk",
+    "x-latchway-sdk-version",
+]);
+const forbiddenCredentialQueryNames = new Set([
+    ...forbiddenCredentialHeaders,
+    "refresh_token",
+    "identity_token",
+    "private_key",
+    "client_data_hash",
+    "request_hash",
+    "integrity_token",
+]);
+const forbiddenCredentialNameFragments = [
+    "authorization",
+    "dpop",
+    "apikey",
+    "accesstoken",
+    "authtoken",
+    "refreshtoken",
+    "identitytoken",
+    "integritytoken",
+    "sessiontoken",
+    "privatekey",
+    "clientsecret",
+    "credential",
+    "attestationevidence",
+    "clientdatahash",
+    "requesthash",
+    "xamzsignature",
+    "xgoogsignature",
+];
+const forbiddenExactCredentialNames = new Set([
+    "key", "token", "secret", "bearer", "cookie", "password", "passwd",
+]);
+const safeResponseHeaderNames = new Set([
+    "accept-ranges",
+    "age",
+    "cache-control",
+    "content-encoding",
+    "content-language",
+    "content-length",
+    "content-range",
+    "content-type",
+    "date",
+    "etag",
+    "expires",
+    "last-modified",
+    "request-id",
+    "retry-after",
+    "server-timing",
+    "vary",
+    "x-request-id",
+    "x-latchway-operation-id",
+    "x-latchway-request-id",
+    "x-latchway-server-version",
+]);
+const nativeControlledHeaders = new Set([
+    "x-latchway-feature",
+    "x-latchway-framework",
+    "x-latchway-framework-version",
+    "x-latchway-protocol-version",
+    "x-latchway-request-id",
+    "x-latchway-sdk",
+    "x-latchway-sdk-version",
+]);
+let nextOperationID = 1;
+export class DefaultLatchwayClient {
+    config;
+    gatewayURL;
+    ready;
+    lease;
+    disposed = false;
+    constructor(config) {
+        this.config = config;
+        this.gatewayURL = config.baseURL.origin;
+        this.lease = acquire(config);
+        this.ready = this.lease.then(async (lease) => { await lease.ready; });
+    }
+    async fetch(input, init = {}) {
+        this.assertActive();
+        const { latchwayFeature, ...requestInit } = init;
+        const bodyExpected = requestBodyExpected(input, requestInit);
+        const request = this.createRequest(input, requestInit);
+        const feature = latchwayFeature ?? request.headers.get("X-Latchway-Feature") ?? undefined;
+        assertFeature(feature);
+        this.assertGatewayTarget(request.url, request.method, feature);
+        if (request.bodyUsed) {
+            throw new LatchwayError("request_not_replayable", "The request body has already been consumed.");
+        }
+        const lease = await this.lease;
+        await lease.ready;
+        const signal = request.signal;
+        const headers = sanitizedRequestHeaders(request.headers);
+        const bodyBase64 = await encodedRequestBody(request, signal, bodyExpected);
+        const requestJSON = JSON.stringify({
+            url: request.url,
+            method: request.method.toUpperCase(),
+            feature,
+            headers,
+            bodyBase64,
+        });
+        if (new TextEncoder().encode(requestJSON).byteLength > MAXIMUM_NATIVE_REQUEST_BYTES) {
+            throw new LatchwayError("request_invalid", "The Latchway request exceeds the native bridge limit.");
+        }
+        const operationID = makeOperationID();
+        const identityToken = await token(this.config.getIdentityToken, signal);
+        const start = lease.module.startRequest(lease.clientID, operationID, identityToken, requestJSON);
+        const observedStart = start.then(async (value) => {
+            if (signal.aborted) {
+                const responseID = recoverResponseID(value);
+                if (responseID !== undefined)
+                    await ignoreFailure(lease.module.closeResponse(lease.clientID, responseID));
+            }
+            return value;
+        });
+        const encoded = await abortable(observedStart, signal, () => { lease.module.cancel(lease.clientID, operationID); });
+        let metadata;
+        try {
+            metadata = parseResponseMetadata(encoded);
+        }
+        catch (cause) {
+            const responseID = recoverResponseID(encoded);
+            if (responseID !== undefined)
+                await ignoreFailure(lease.module.closeResponse(lease.clientID, responseID));
+            throw cause;
+        }
+        if (signal.aborted) {
+            await ignoreFailure(lease.module.closeResponse(lease.clientID, metadata.responseID));
+            throw abortError();
+        }
+        const hasBody = request.method.toUpperCase() !== "HEAD" &&
+            metadata.status !== 204 && metadata.status !== 205 && metadata.status !== 304;
+        const body = hasBody ? nativeResponseBody(lease, metadata.responseID, signal) : null;
+        if (!hasBody)
+            await ignoreFailure(lease.module.closeResponse(lease.clientID, metadata.responseID));
+        return responseWithNativeBody(body, {
+            status: metadata.status,
+            statusText: metadata.statusText,
+            headers: metadata.headers,
+        });
+    }
+    fetchFor(feature) {
+        this.assertActive();
+        assertFeature(feature);
+        return async (input, init = {}) => aliasFrameworkRequestID(await this.fetch(input, { ...init, latchwayFeature: feature }));
+    }
+    async quota(feature) {
+        this.assertActive();
+        assertFeature(feature);
+        const encoded = await this.nativeString("quota", undefined, feature);
+        return parseQuota(encoded, feature);
+    }
+    async diagnostics() {
+        this.assertActive();
+        const lease = await this.lease;
+        const compatibility = await lease.ready;
+        const encoded = await this.nativeString("diagnostics");
+        return parseDiagnostics(encoded, compatibility.platform, compatibility.nativeSDKVersion);
+    }
+    async refresh() {
+        this.assertActive();
+        await this.nativeVoid("refresh");
+    }
+    async prepareComponents(components) {
+        this.assertActive();
+        const componentsJSON = encodeIOSComponentDescriptors(components, this.config.appleSharedKeychainAccessGroups);
+        const snapshot = JSON.parse(componentsJSON);
+        const encoded = await this.nativeComponentOperation("prepare", componentsJSON);
+        return parsePreparedComponents(encoded, snapshot);
+    }
+    async revokeComponent(component) {
+        this.assertActive();
+        const componentJSON = encodeIOSComponentDescriptor(component, this.config.appleSharedKeychainAccessGroups);
+        await this.nativeComponentOperation("revokeComponent", componentJSON);
+    }
+    async replaceComponent(component) {
+        this.assertActive();
+        const componentJSON = encodeIOSComponentDescriptor(component, this.config.appleSharedKeychainAccessGroups);
+        const snapshot = JSON.parse(componentJSON);
+        const encoded = await this.nativeComponentOperation("replace", componentJSON);
+        return parseComponentDiagnostics(encoded, snapshot);
+    }
+    async componentDiagnostics(component) {
+        this.assertActive();
+        const componentJSON = encodeIOSComponentDescriptor(component, this.config.appleSharedKeychainAccessGroups);
+        const snapshot = JSON.parse(componentJSON);
+        const lease = await this.lease;
+        await lease.ready;
+        const operationID = makeOperationID();
+        const operation = lease.module.rootComponentDiagnostics(lease.clientID, operationID, componentJSON);
+        const encoded = await abortable(operation, undefined, () => {
+            lease.module.cancel(lease.clientID, operationID);
+        });
+        return parseComponentDiagnostics(encoded, snapshot);
+    }
+    async revokeCurrentInstallation() {
+        this.assertActive();
+        await this.nativeVoid("revoke");
+    }
+    async revokeCurrentInstallationFamily(retiring = []) {
+        this.assertActive();
+        if (retiring.length === 0) {
+            await this.nativeVoid("revokeFamily");
+            return;
+        }
+        const componentsJSON = encodeIOSComponentDescriptors(retiring, this.config.appleSharedKeychainAccessGroups);
+        await this.nativeComponentOperation("revokeFamily", componentsJSON);
+    }
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        const lease = await this.lease;
+        await lease.release();
+    }
+    async nativeString(method, signal, argument) {
+        const lease = await this.lease;
+        await lease.ready;
+        const operationID = makeOperationID();
+        const identityToken = await token(this.config.getIdentityToken, signal);
+        const operation = method === "quota"
+            ? lease.module.quota(lease.clientID, operationID, identityToken, argument ?? "")
+            : lease.module.diagnostics(lease.clientID, operationID, identityToken);
+        return abortable(operation, signal, () => { lease.module.cancel(lease.clientID, operationID); });
+    }
+    async nativeVoid(method, signal) {
+        const lease = await this.lease;
+        await lease.ready;
+        const operationID = makeOperationID();
+        const identityToken = await token(this.config.getIdentityToken, signal);
+        const operation = method === "refresh"
+            ? lease.module.refresh(lease.clientID, operationID, identityToken)
+            : method === "revoke"
+                ? lease.module.revoke(lease.clientID, operationID, identityToken)
+                : lease.module.revokeFamily(lease.clientID, operationID, identityToken);
+        await abortable(operation, signal, () => { lease.module.cancel(lease.clientID, operationID); });
+    }
+    async nativeComponentOperation(method, encodedDescriptor, signal) {
+        const lease = await this.lease;
+        await lease.ready;
+        const operationID = makeOperationID();
+        const identityToken = await token(this.config.getIdentityToken, signal);
+        const operation = method === "prepare"
+            ? lease.module.prepareComponents(lease.clientID, operationID, identityToken, encodedDescriptor)
+            : method === "replace"
+                ? lease.module.replaceComponent(lease.clientID, operationID, identityToken, encodedDescriptor)
+                : method === "revokeComponent"
+                    ? lease.module.revokeComponent(lease.clientID, operationID, identityToken, encodedDescriptor)
+                        .then(() => "")
+                    : lease.module.revokeFamilyWithComponents(lease.clientID, operationID, identityToken, encodedDescriptor)
+                        .then(() => "");
+        return abortable(operation, signal, () => { lease.module.cancel(lease.clientID, operationID); });
+    }
+    createRequest(input, init) {
+        if (input instanceof Request && Reflect.ownKeys(init).length === 0)
+            return input;
+        if (input instanceof Request)
+            return new Request(input, init);
+        const resolved = input instanceof URL ? input : new URL(input, this.config.baseURL);
+        return new Request(resolved, init);
+    }
+    assertGatewayTarget(input, method, feature) {
+        const target = new URL(input);
+        const pathname = policyPathname(input, target);
+        if (target.origin !== this.config.baseURL.origin || target.hash !== "") {
+            throw new LatchwayError("client_configuration_invalid", "Latchway only dispatches requests to the configured gateway origin.");
+        }
+        if (!isAllowedDataPlaneTarget(target, pathname, method, feature)) {
+            throw new LatchwayError("transport_destination_not_allowed", "Latchway only authorizes methods and paths declared by the client contract.");
+        }
+        target.searchParams.forEach((_value, name) => {
+            if (isForbiddenCredentialName(decodedCredentialName(name))) {
+                throw new LatchwayError("request_invalid", "Upstream provider credentials must not be supplied in the request URL.");
+            }
+        });
+    }
+    assertActive() {
+        if (this.disposed) {
+            throw new LatchwayError("client_configuration_invalid", "This Latchway client has been disposed.");
+        }
+    }
+}
+function parsePreparedComponents(encoded, expected) {
+    let value;
+    try {
+        value = JSON.parse(encoded);
+    }
+    catch {
+        throw invalidPreparedComponents();
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value) ||
+        Reflect.ownKeys(value).length !== 1 || !("components" in value) ||
+        !Array.isArray(value.components) || value.components.length !== expected.length) {
+        throw invalidPreparedComponents();
+    }
+    try {
+        return value.components.map((diagnostics, index) => {
+            const component = expected[index];
+            if (component === undefined)
+                throw invalidPreparedComponents();
+            return parseComponentDiagnostics(JSON.stringify(diagnostics), component);
+        });
+    }
+    catch (cause) {
+        if (cause instanceof LatchwayError)
+            throw cause;
+        throw invalidPreparedComponents();
+    }
+}
+function invalidPreparedComponents() {
+    return new LatchwayError("protocol_response_invalid", "Latchway native component output was invalid.");
+}
+/**
+ * Provider SDKs conventionally read `X-Request-ID`. Preserve Latchway's
+ * canonical header and add the alias without consuming or buffering the body.
+ */
+function aliasFrameworkRequestID(response) {
+    const requestID = response.headers.get("X-Latchway-Request-ID");
+    if (requestID === null || response.headers.get("X-Request-ID") === requestID)
+        return response;
+    response.headers.set("X-Request-ID", requestID);
+    return response;
+}
+function responseWithNativeBody(body, init) {
+    let response;
+    try {
+        response = new Response(body, init);
+    }
+    catch {
+        // Some React Native Response implementations reject ponyfill streams even
+        // though the instance body is attached below and consumed directly.
+        response = new Response(null, init);
+    }
+    if (body === null)
+        return response;
+    const exposed = response.body;
+    if (exposed !== undefined && exposed !== null && typeof exposed.getReader === "function") {
+        return response;
+    }
+    // React Native 0.82's built-in Response accepts the stream but does not
+    // expose it through `body`. Restore the exact native-owned pull stream on
+    // the instance; no bytes are buffered and the native cancel/close lifecycle
+    // remains authoritative.
+    Object.defineProperty(response, "body", {
+        configurable: true,
+        enumerable: true,
+        value: body,
+    });
+    return response;
+}
+function policyPathname(input, target) {
+    // React Native's built-in URL polyfill appends `/` when an absolute URL has
+    // no query or fragment. Request.url is already serialized at this point, so
+    // recognize only that exact mutation instead of broadening the route set to
+    // accept genuinely trailing-slash destinations.
+    if (target.pathname.length > 1 && !input.includes("?") && !input.includes("#") &&
+        !input.endsWith("/") && target.href === `${input}/`) {
+        return target.pathname.slice(0, -1);
+    }
+    return target.pathname;
+}
+function isAllowedDataPlaneTarget(target, pathname, method, feature) {
+    const normalizedMethod = method.toUpperCase();
+    if (normalizedMethod === "POST" && allowedDataPlanePaths.has(pathname))
+        return true;
+    const prefix = `/proxy/${encodeURIComponent(feature)}/`;
+    if (!opaqueDataPlaneMethods.has(normalizedMethod) || target.search !== "" ||
+        !pathname.startsWith(prefix))
+        return false;
+    const remaining = pathname.slice(prefix.length);
+    const lowerRemaining = remaining.toLowerCase();
+    return remaining.length >= 1 && remaining.length <= 2_048 &&
+        remaining.split("/").every((segment) => segment !== "" && segment !== "." && segment !== "..") &&
+        !lowerRemaining.includes("%2e") && !lowerRemaining.includes("%2f") &&
+        !lowerRemaining.includes("%5c") && !remaining.includes("\\") &&
+        !lowerRemaining.startsWith("http:") && !lowerRemaining.startsWith("https:");
+}
+function sanitizedRequestHeaders(source) {
+    const result = [];
+    let size = 0;
+    source.forEach((value, name) => {
+        const normalized = name.toLowerCase();
+        if (nativeControlledHeaders.has(normalized))
+            return;
+        if (isForbiddenCredentialName(normalized))
+            return;
+        if (!isHeaderName(normalized) || !isHeaderValue(value)) {
+            throw new LatchwayError("request_invalid", "The request contains an invalid header.");
+        }
+        size += normalized.length + value.length;
+        if (result.length >= MAXIMUM_HEADERS || size > MAXIMUM_HEADER_BYTES) {
+            throw new LatchwayError("request_invalid", "The request headers exceed the native bridge limit.");
+        }
+        result.push([normalized, value]);
+    });
+    return result;
+}
+function requestBodyExpected(input, init) {
+    if (Object.prototype.hasOwnProperty.call(init, "body"))
+        return init.body !== null && init.body !== undefined;
+    if (!(input instanceof Request))
+        return false;
+    const body = input.body;
+    if (body !== null && body !== undefined)
+        return true;
+    return input._bodyInit !== null &&
+        input._bodyInit !== undefined;
+}
+async function encodedRequestBody(request, signal, bodyExpected) {
+    const body = request.body;
+    if (body === null || (body === undefined && !bodyExpected))
+        return null;
+    if (body === undefined || typeof body.getReader !== "function") {
+        try {
+            const encoded = await abortable(request.arrayBuffer(), signal, () => { });
+            const bytes = new Uint8Array(encoded);
+            if (bytes.byteLength > MAXIMUM_REQUEST_BODY_BYTES) {
+                throw new LatchwayError("request_invalid", "The request body exceeds the 8 MiB native transport limit.");
+            }
+            return bytesToBase64(bytes);
+        }
+        catch (cause) {
+            if (cause instanceof LatchwayError || isAbort(cause))
+                throw cause;
+            throw new LatchwayError("request_not_replayable", "The request body could not be read for native dispatch.", { cause });
+        }
+    }
+    const reader = body.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        for (;;) {
+            const result = await readWithAbort(reader, signal);
+            if (result.done)
+                break;
+            size += result.value.byteLength;
+            if (size > MAXIMUM_REQUEST_BODY_BYTES) {
+                await reader.cancel("Latchway request body limit exceeded");
+                throw new LatchwayError("request_invalid", "The request body exceeds the 8 MiB native transport limit.");
+            }
+            chunks.push(result.value);
+        }
+    }
+    catch (cause) {
+        if (cause instanceof LatchwayError || isAbort(cause))
+            throw cause;
+        throw new LatchwayError("request_not_replayable", "The request body could not be read for native dispatch.", { cause });
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bytesToBase64(bytes);
+}
+async function readWithAbort(reader, signal) {
+    if (signal.aborted) {
+        void reader.cancel();
+        throw abortError();
+    }
+    let listener;
+    const aborted = new Promise((_resolve, reject) => {
+        listener = () => {
+            void reader.cancel();
+            reject(abortError());
+        };
+        signal.addEventListener("abort", listener, { once: true });
+    });
+    try {
+        return await Promise.race([reader.read(), aborted]);
+    }
+    finally {
+        if (listener !== undefined)
+            signal.removeEventListener("abort", listener);
+    }
+}
+function nativeResponseBody(lease, responseID, signal) {
+    let finished = false;
+    let nativeClosed = false;
+    let activeOperationID;
+    let abortListener;
+    const closeNative = async () => {
+        if (nativeClosed)
+            return;
+        nativeClosed = true;
+        await ignoreFailure(lease.module.closeResponse(lease.clientID, responseID));
+    };
+    const finish = () => {
+        if (finished)
+            return;
+        finished = true;
+        if (abortListener !== undefined)
+            signal.removeEventListener("abort", abortListener);
+    };
+    const ReadableStreamConstructor = typeof globalThis.ReadableStream === "function"
+        ? globalThis.ReadableStream
+        : PonyfillReadableStream;
+    return new ReadableStreamConstructor({
+        start(controller) {
+            abortListener = () => {
+                if (finished)
+                    return;
+                finish();
+                void closeNative();
+                controller.error(abortError());
+            };
+            signal.addEventListener("abort", abortListener, { once: true });
+        },
+        async pull(controller) {
+            if (finished)
+                return;
+            if (signal.aborted) {
+                finish();
+                await closeNative();
+                controller.error(abortError());
+                return;
+            }
+            const operationID = makeOperationID();
+            activeOperationID = operationID;
+            try {
+                const encoded = await abortable(lease.module.readResponseChunk(lease.clientID, operationID, responseID, MAXIMUM_RESPONSE_CHUNK_BYTES), signal, () => { lease.module.cancel(lease.clientID, operationID); });
+                const chunk = parseResponseChunk(encoded);
+                if (chunk.done) {
+                    finish();
+                    controller.close();
+                    await closeNative();
+                }
+                else if (chunk.chunk !== undefined) {
+                    controller.enqueue(chunk.chunk);
+                }
+            }
+            catch (cause) {
+                if (!finished) {
+                    finish();
+                    controller.error(isAbort(cause) ? abortError() : cause);
+                }
+                await closeNative();
+            }
+            finally {
+                if (activeOperationID === operationID)
+                    activeOperationID = undefined;
+            }
+        },
+        async cancel() {
+            finish();
+            if (activeOperationID !== undefined)
+                lease.module.cancel(lease.clientID, activeOperationID);
+            await closeNative();
+        },
+    }, { highWaterMark: 0 });
+}
+function parseResponseMetadata(encoded) {
+    const value = parseRecord(encoded, "native response metadata");
+    assertNoCredentialFields(value);
+    if (!hasOnlyKeys(value, ["responseID", "status", "statusText", "headers"]) ||
+        typeof value.responseID !== "string" || !/^rsp_[A-Za-z0-9_-]{16,96}$/u.test(value.responseID) ||
+        !Number.isInteger(value.status) || value.status < 200 || value.status > 599 ||
+        typeof value.statusText !== "string" || value.statusText.length > 128 || /\p{Cc}/u.test(value.statusText) ||
+        !Array.isArray(value.headers) || value.headers.length > MAXIMUM_HEADERS) {
+        throw new LatchwayError("protocol_response_invalid", "Latchway returned invalid native response metadata.");
+    }
+    const headers = [];
+    let headerBytes = 0;
+    for (const header of value.headers) {
+        if (!Array.isArray(header) || header.length !== 2 || typeof header[0] !== "string" ||
+            typeof header[1] !== "string") {
+            throw new LatchwayError("protocol_response_invalid", "Latchway returned invalid native response headers.");
+        }
+        const name = header[0].toLowerCase();
+        const headerValue = header[1];
+        if (!isSafeResponseHeader(name) || !isHeaderValue(headerValue)) {
+            throw new LatchwayError("protocol_response_invalid", "Latchway returned unsafe native response headers.");
+        }
+        headerBytes += name.length + headerValue.length;
+        if (headerBytes > MAXIMUM_HEADER_BYTES) {
+            throw new LatchwayError("protocol_response_invalid", "Latchway returned oversized native response headers.");
+        }
+        headers.push([name, headerValue]);
+    }
+    return {
+        responseID: value.responseID,
+        status: value.status,
+        statusText: value.statusText,
+        headers,
+    };
+}
+function parseResponseChunk(encoded) {
+    if (encoded.length > MAXIMUM_RESPONSE_CHUNK_BYTES * 2) {
+        throw new LatchwayError("protocol_response_invalid", "Latchway returned an oversized native response chunk.");
+    }
+    const value = parseRecord(encoded, "native response chunk");
+    assertNoCredentialFields(value);
+    if (!hasOnlyKeys(value, ["done", "chunk"]) || typeof value.done !== "boolean") {
+        throw new LatchwayError("protocol_response_invalid", "Latchway returned an invalid native response chunk.");
+    }
+    if (value.done) {
+        if (value.chunk !== undefined && value.chunk !== null) {
+            throw new LatchwayError("protocol_response_invalid", "Latchway returned an invalid final native response chunk.");
+        }
+        return { done: true };
+    }
+    if (typeof value.chunk !== "string") {
+        throw new LatchwayError("protocol_response_invalid", "Latchway omitted native response bytes.");
+    }
+    const chunk = base64ToBytes(value.chunk);
+    if (chunk.byteLength === 0 || chunk.byteLength > MAXIMUM_RESPONSE_CHUNK_BYTES) {
+        throw new LatchwayError("protocol_response_invalid", "Latchway returned invalid native response bytes.");
+    }
+    return { done: false, chunk };
+}
+function parseQuota(encoded, expectedFeature) {
+    const value = parseRecord(encoded, "quota snapshot");
+    assertNoCredentialFields(value);
+    if (!hasOnlyKeys(value, ["feature", "observed_at", "limits"]) ||
+        value.feature !== expectedFeature || typeof value.observed_at !== "string" || !Array.isArray(value.limits)) {
+        throw new LatchwayError("protocol_response_invalid", "Latchway returned an invalid quota snapshot.");
+    }
+    const limits = value.limits.map((item) => {
+        if (!isRecord(item) ||
+            !hasOnlyKeys(item, ["metric", "maximum", "used", "reserved", "remaining", "resets_at", "hard"]) ||
+            typeof item.metric !== "string" || typeof item.hard !== "boolean") {
+            throw new LatchwayError("protocol_response_invalid", "Latchway returned an invalid quota limit.");
+        }
+        for (const field of ["maximum", "used", "reserved", "remaining"]) {
+            const counter = item[field];
+            if (counter !== undefined && (!Number.isSafeInteger(counter) || counter < 0)) {
+                throw new LatchwayError("protocol_response_invalid", "Latchway returned an invalid quota counter.");
+            }
+        }
+        if (item.resets_at !== undefined && typeof item.resets_at !== "string") {
+            throw new LatchwayError("protocol_response_invalid", "Latchway returned an invalid quota reset time.");
+        }
+        return item;
+    });
+    return { feature: expectedFeature, observed_at: value.observed_at, limits };
+}
+function parseDiagnostics(encoded, platform, nativeSDKVersion) {
+    const value = parseRecord(encoded, "diagnostics");
+    assertNoCredentialFields(value);
+    if (!hasOnlyKeys(value, [
+        "contractVersion", "protocolVersion", "keyStorage", "attestation", "session", "installation", "server",
+        "lastErrorCode",
+    ]) || value.contractVersion !== CONTRACT_VERSION || value.protocolVersion !== PROTOCOL_VERSION ||
+        typeof value.keyStorage !== "string" || !isRecord(value.attestation) || !isRecord(value.session) ||
+        !isRecord(value.installation) || !isRecord(value.server)) {
+        throw new LatchwayError("protocol_response_invalid", "Latchway returned invalid native diagnostics.");
+    }
+    if (!hasOnlyKeys(value.attestation, ["support", "provider", "trustLevel", "lastOperation"]) ||
+        !hasOnlyKeys(value.session, ["state", "expiresAt", "refreshAvailable"]) ||
+        !hasOnlyKeys(value.installation, ["id", "status"]) ||
+        !hasOnlyKeys(value.server, ["version", "lastRequestID"])) {
+        throw new LatchwayError("protocol_response_invalid", "Latchway returned unexpected native diagnostics.");
+    }
+    const support = value.attestation.support;
+    const state = value.session.state;
+    if ((support !== "supported" && support !== "unsupported" && support !== "unknown") ||
+        typeof state !== "string" ||
+        !new Set(["absent", "establishing", "active", "refreshing", "expired", "revoked", "failed"]).has(state)) {
+        throw new LatchwayError("protocol_response_invalid", "Latchway returned invalid native diagnostic state.");
+    }
+    const provider = optionalString(value.attestation.provider);
+    const trustLevel = optionalString(value.attestation.trustLevel);
+    const lastOperation = optionalString(value.attestation.lastOperation);
+    const expiresAt = optionalString(value.session.expiresAt);
+    const installationID = optionalString(value.installation.id);
+    const installationStatus = optionalString(value.installation.status);
+    const serverVersion = optionalString(value.server.version);
+    const lastRequestID = optionalString(value.server.lastRequestID);
+    const lastErrorCode = optionalString(value.lastErrorCode);
+    return {
+        sdkVersion: SDK_VERSION,
+        nativeSDKVersion,
+        contractVersion: CONTRACT_VERSION,
+        protocolVersion: PROTOCOL_VERSION,
+        platform,
+        keyStorage: value.keyStorage,
+        attestation: {
+            support,
+            ...(provider === undefined ? {} : { provider }),
+            ...(trustLevel === undefined ? {} : { trustLevel }),
+            ...(lastOperation === undefined ? {} : { lastOperation }),
+        },
+        session: {
+            state: state,
+            ...(expiresAt === undefined ? {} : { expiresAt }),
+            ...(typeof value.session.refreshAvailable === "boolean" ? { refreshAvailable: value.session.refreshAvailable } : {}),
+        },
+        installation: {
+            ...(installationID === undefined ? {} : { id: installationID }),
+            ...(installationStatus === undefined ? {} : { status: installationStatus }),
+        },
+        server: {
+            ...(serverVersion === undefined ? {} : { version: serverVersion }),
+            ...(lastRequestID === undefined ? {} : { lastRequestID }),
+        },
+        ...(lastErrorCode === undefined ? {} : { lastErrorCode }),
+    };
+}
+async function token(provider, signal) {
+    let result;
+    try {
+        result = await abortable(Promise.resolve().then(provider), signal);
+    }
+    catch (cause) {
+        if (isAbort(cause))
+            throw cause;
+        throw new LatchwayError("identity_token_invalid", "The identity token provider failed.", { cause });
+    }
+    if (typeof result !== "string" || result.length === 0 || result.length > 65_536 || /\p{Cc}/u.test(result)) {
+        throw new LatchwayError("identity_token_invalid", "The identity token provider returned an invalid token.");
+    }
+    return result;
+}
+async function abortable(operation, signal, cancel) {
+    if (signal === undefined) {
+        try {
+            return await operation;
+        }
+        catch (cause) {
+            throw fromNativeError(cause);
+        }
+    }
+    if (signal.aborted) {
+        cancel?.();
+        throw abortError();
+    }
+    let listener;
+    const aborted = new Promise((_resolve, reject) => {
+        listener = () => {
+            cancel?.();
+            reject(abortError());
+        };
+        signal.addEventListener("abort", listener, { once: true });
+    });
+    try {
+        return await Promise.race([operation.catch((cause) => { throw fromNativeError(cause); }), aborted]);
+    }
+    finally {
+        if (listener !== undefined)
+            signal.removeEventListener("abort", listener);
+    }
+}
+function makeOperationID() {
+    return `op-${nextOperationID++}`;
+}
+function assertFeature(value) {
+    if (value === undefined || !validIdentifier(value)) {
+        throw new LatchwayError("client_configuration_invalid", "A valid latchwayFeature is required.");
+    }
+}
+function validIdentifier(value) {
+    return /^[a-z][a-z0-9_-]{0,62}$/u.test(value);
+}
+function parseRecord(encoded, label) {
+    try {
+        const value = JSON.parse(encoded);
+        if (isRecord(value))
+            return value;
+    }
+    catch {
+        // Native output is intentionally not reflected into the safe error.
+    }
+    throw new LatchwayError("protocol_response_invalid", `Latchway returned invalid ${label}.`);
+}
+function hasOnlyKeys(value, names) {
+    const expected = new Set(names);
+    return Object.keys(value).every((name) => expected.has(name));
+}
+function isSafeResponseHeader(name) {
+    return safeResponseHeaderNames.has(name) || name.startsWith("x-ratelimit-") || name.startsWith("ratelimit-");
+}
+function recoverResponseID(encoded) {
+    if (encoded.length > 256 * 1024)
+        return undefined;
+    try {
+        const value = JSON.parse(encoded);
+        if (isRecord(value) && typeof value.responseID === "string" && /^rsp_[A-Za-z0-9_-]{16,96}$/u.test(value.responseID)) {
+            return value.responseID;
+        }
+    }
+    catch {
+        // Invalid output has no safely recoverable response handle.
+    }
+    return undefined;
+}
+function isHeaderName(value) {
+    return /^[!#$%&'*+.^_`|~0-9A-Za-z-]{1,128}$/u.test(value);
+}
+function isHeaderValue(value) {
+    if (value.length > 8_192)
+        return false;
+    for (const character of value) {
+        const scalar = character.codePointAt(0) ?? 0;
+        if (scalar <= 0x08 || (scalar >= 0x0a && scalar <= 0x1f) || scalar === 0x7f)
+            return false;
+    }
+    return true;
+}
+function decodedCredentialName(value) {
+    let decoded = value;
+    for (let attempt = 0; attempt < 4; attempt += 1) {
+        try {
+            const next = decodeURIComponent(decoded);
+            if (next === decoded)
+                break;
+            decoded = next;
+        }
+        catch {
+            break;
+        }
+    }
+    // Fail closed on deeper nested escapes instead of letting an attacker move a
+    // credential name past the bounded decoder with another layer of `%25`.
+    if (/%[0-9A-Fa-f]{2}/u.test(decoded))
+        return "credential-encoded-name";
+    return decoded.toLowerCase();
+}
+function isForbiddenCredentialName(value) {
+    const normalized = value.toLowerCase();
+    if (forbiddenCredentialHeaders.has(normalized) || forbiddenCredentialQueryNames.has(normalized))
+        return true;
+    const compact = normalized.replace(/[^a-z0-9]/gu, "");
+    return forbiddenExactCredentialNames.has(compact) ||
+        forbiddenCredentialNameFragments.some((fragment) => compact.includes(fragment));
+}
+function bytesToBase64(bytes) {
+    let binary = "";
+    for (let offset = 0; offset < bytes.length; offset += 16_384) {
+        const end = Math.min(offset + 16_384, bytes.length);
+        for (let index = offset; index < end; index += 1)
+            binary += String.fromCharCode(bytes[index] ?? 0);
+    }
+    return btoa(binary);
+}
+function base64ToBytes(encoded) {
+    if (encoded.length === 0 || encoded.length % 4 !== 0 || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(encoded)) {
+        throw new LatchwayError("protocol_response_invalid", "Latchway returned malformed native response bytes.");
+    }
+    let binary;
+    try {
+        binary = atob(encoded);
+    }
+    catch {
+        throw new LatchwayError("protocol_response_invalid", "Latchway returned malformed native response bytes.");
+    }
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1)
+        bytes[index] = binary.charCodeAt(index);
+    if (bytesToBase64(bytes) !== encoded) {
+        throw new LatchwayError("protocol_response_invalid", "Latchway returned non-canonical native response bytes.");
+    }
+    return bytes;
+}
+function optionalString(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "string" || value.length === 0 || value.length > 512 || /\p{Cc}/u.test(value)) {
+        throw new LatchwayError("protocol_response_invalid", "Latchway returned an invalid native diagnostic value.");
+    }
+    return value;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isAbort(value) {
+    return value instanceof Error && value.name === "AbortError";
+}
+async function ignoreFailure(operation) {
+    try {
+        await operation;
+    }
+    catch { /* cleanup is idempotent and best-effort */ }
+}
+//# sourceMappingURL=client.js.map