@qlever-llc/trellis 0.7.0 → 0.8.0-rc.2

package/script/npm/src/client_connect.js

@@ -0,0 +1,814 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TrellisClient = exports.ClientAuthHandledError = void 0;
+exports.connectClientWithDeps = connectClientWithDeps;
+const dntShim = __importStar(require("./_dnt.shims.js"));
+const nats_core_1 = require("@nats-io/nats-core");
+const mod_js_1 = require("./contract_support/mod.js");
+const browser_js_1 = require("./auth/browser.js");
+const browser_js_2 = require("./auth/browser.js");
+const time_js_1 = require("./auth/time.js");
+const session_auth_js_1 = require("./auth/session_auth.js");
+const utils_js_1 = require("./auth/utils.js");
+const keys_js_1 = require("./auth/keys.js");
+const runtime_transport_js_1 = require("./runtime_transport.js");
+const trellis_js_1 = require("./trellis.js");
+const index_js_1 = require("./errors/index.js");
+const result_1 = require("@qlever-llc/result");
+const typebox_1 = require("typebox");
+const value_1 = require("typebox/value");
+const session_js_1 = require("./auth/browser/session.js");
+const connection_js_1 = require("./connection.js");
+function createConnectedClient(args) {
+    const trellis = new trellis_js_1.Trellis(args.name, args.nc, {
+        sessionKey: args.sessionKey,
+        sign: args.sign,
+    }, {
+        ...args.opts,
+        connection: args.connection,
+    });
+    return trellis;
+}
+function clientConnectResult(promise) {
+    return result_1.AsyncResult.from(promise.then((value) => result_1.Result.ok(value), (cause) => result_1.Result.err(cause instanceof index_js_1.TransportError
+        ? cause
+        : new result_1.UnexpectedError({ cause }))));
+}
+/**
+ * Error raised when client authentication was delegated to caller-owned routing.
+ */
+class ClientAuthHandledError extends Error {
+    constructor() {
+        super("Client authentication was handled by the caller");
+        this.name = "ClientAuthHandledError";
+    }
+}
+exports.ClientAuthHandledError = ClientAuthHandledError;
+const ClientTransportEndpointsSchema = typebox_1.Type.Object({
+    natsServers: typebox_1.Type.Array(typebox_1.Type.String({ minLength: 1 }), { minItems: 1 }),
+});
+const ClientTransportsSchema = typebox_1.Type.Object({
+    native: typebox_1.Type.Optional(ClientTransportEndpointsSchema),
+    websocket: typebox_1.Type.Optional(ClientTransportEndpointsSchema),
+});
+const ClientBootstrapReadySchema = typebox_1.Type.Object({
+    status: typebox_1.Type.Literal("ready"),
+    serverNow: typebox_1.Type.Integer(),
+    connectInfo: typebox_1.Type.Object({
+        sessionKey: typebox_1.Type.String({ minLength: 1 }),
+        contractId: typebox_1.Type.String({ minLength: 1 }),
+        contractDigest: typebox_1.Type.String({ minLength: 1 }),
+        transports: ClientTransportsSchema,
+        transport: typebox_1.Type.Object({
+            inboxPrefix: typebox_1.Type.String({ minLength: 1 }),
+            sentinel: typebox_1.Type.Object({
+                jwt: typebox_1.Type.String({ minLength: 1 }),
+                seed: typebox_1.Type.String({ minLength: 1 }),
+            }),
+        }),
+    }),
+}, { additionalProperties: true });
+const ClientBootstrapAuthRequiredSchema = typebox_1.Type.Object({
+    status: typebox_1.Type.Literal("auth_required"),
+    serverNow: typebox_1.Type.Integer(),
+}, { additionalProperties: true });
+const ClientBootstrapNotReadySchema = typebox_1.Type.Object({
+    status: typebox_1.Type.Literal("not_ready"),
+    reason: typebox_1.Type.String({ minLength: 1 }),
+    serverNow: typebox_1.Type.Integer(),
+}, { additionalProperties: true });
+const ClientBootstrapIatOutOfRangeSchema = typebox_1.Type.Object({
+    reason: typebox_1.Type.Literal("iat_out_of_range"),
+    serverNow: typebox_1.Type.Integer(),
+}, { additionalProperties: true });
+function isBrowserRuntime() {
+    return typeof dntShim.dntGlobalThis !== "undefined" && typeof document !== "undefined";
+}
+const defaultDeps = {
+    loadTransport: runtime_transport_js_1.loadDefaultRuntimeTransport,
+    now: () => Date.now(),
+    setInterval: (handler, ms) => globalThis.setInterval(handler, ms),
+    clearInterval: (id) => globalThis.clearInterval(id),
+};
+function transportCauseContext(cause) {
+    if (cause instanceof Error) {
+        return { causeName: cause.name, causeMessage: cause.message };
+    }
+    return { cause: String(cause) };
+}
+function createTransportError(args) {
+    return new index_js_1.TransportError({
+        code: args.code,
+        message: args.message,
+        hint: args.hint,
+        cause: args.cause,
+        context: {
+            ...(args.context ?? {}),
+            ...(args.cause === undefined ? {} : transportCauseContext(args.cause)),
+        },
+    });
+}
+async function readJsonResponse(response, args) {
+    try {
+        return await response.json();
+    }
+    catch (cause) {
+        throw createTransportError({
+            ...args,
+            cause,
+        });
+    }
+}
+function normalizeTrellisUrl(trellisUrl) {
+    return new URL(trellisUrl).toString().replace(/\/$/, "");
+}
+function resolveCurrentUrl(auth) {
+    const currentUrl = typeof auth?.currentUrl === "function"
+        ? auth.currentUrl()
+        : auth?.currentUrl;
+    if (currentUrl instanceof URL)
+        return currentUrl;
+    if (typeof currentUrl === "string")
+        return new URL(currentUrl);
+    return null;
+}
+function resolveRedirectTo(auth, currentUrl) {
+    const redirectTo = typeof auth.redirectTo === "function"
+        ? auth.redirectTo()
+        : auth.redirectTo;
+    if (redirectTo) {
+        return new URL(redirectTo, currentUrl.origin).toString();
+    }
+    const queryRedirect = currentUrl.searchParams.get("redirectTo");
+    if (queryRedirect) {
+        return new URL(queryRedirect, currentUrl.origin).toString();
+    }
+    if (auth.landingPath) {
+        return new URL(auth.landingPath, currentUrl.origin).toString();
+    }
+    return currentUrl.toString();
+}
+function resolveConfiguredRedirectTo(redirectTo) {
+    return typeof redirectTo === "function" ? redirectTo() : redirectTo;
+}
+function authRequestContextRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    return value;
+}
+async function signDomainValue(sign, prefix, value) {
+    const digest = await (0, browser_js_2.sha256)((0, browser_js_2.utf8)(`${prefix}:${value}`));
+    const signature = await sign(digest);
+    const binary = String.fromCharCode(...signature);
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+async function createSessionKeyRuntimeIdentity(sessionKeySeed) {
+    const seed = (0, browser_js_1.base64urlDecode)(sessionKeySeed);
+    const privateKey = await (0, keys_js_1.importEd25519PrivateKeyFromSeedBase64url)(sessionKeySeed);
+    const sessionKey = (0, keys_js_1.publicKeyBase64urlFromSeed)(seed);
+    const sign = async (data) => {
+        const signature = await crypto.subtle.sign("Ed25519", privateKey, (0, browser_js_2.toArrayBuffer)(data));
+        return new Uint8Array(signature);
+    };
+    return {
+        mode: "session_key",
+        sessionKey,
+        sign,
+        oauthInitSig: (redirectTo, context, provider, contract) => signDomainValue(sign, "oauth-init", contract === undefined
+            ? `${redirectTo}:${(0, utils_js_1.canonicalizeJsonValue)(context ?? null)}`
+            : `${redirectTo}:${provider ?? ""}:${(0, utils_js_1.canonicalizeJsonValue)(contract)}:${(0, utils_js_1.canonicalizeJsonValue)(context ?? null)}`),
+        natsConnectSigForIat: (iat, contractDigest) => signDomainValue(sign, "nats-connect", (0, session_auth_js_1.buildNatsConnectSignaturePayload)(iat, contractDigest)),
+        bootstrapSig: (iat) => signDomainValue(sign, "bootstrap-client", String(iat)),
+        bindFlowSig: (flowId) => signDomainValue(sign, "bind-flow", flowId),
+        buildRuntimeAuthTokenSync: (iat, contractDigest) => {
+            const sig = (0, keys_js_1.signEd25519SeedSha256)(seed, (0, browser_js_2.utf8)(`nats-connect:${(0, session_auth_js_1.buildNatsConnectSignaturePayload)(iat, contractDigest)}`));
+            return JSON.stringify({
+                v: 1,
+                sessionKey,
+                iat,
+                contractDigest,
+                sig: (0, browser_js_1.base64urlEncode)(new Uint8Array(sig)),
+            });
+        },
+    };
+}
+async function resolveClientIdentity(auth) {
+    if (auth?.mode === "session_key") {
+        return await createSessionKeyRuntimeIdentity(auth.sessionKeySeed);
+    }
+    const handle = auth?.handle ?? await (0, browser_js_1.getOrCreateSessionKey)();
+    return {
+        mode: "browser",
+        sessionKey: (0, browser_js_1.getPublicSessionKey)(handle),
+        sign: (data) => (0, session_js_1.signBytes)(handle, data),
+        oauthInitSig: (redirectTo, context, provider, contract) => (0, session_js_1.oauthInitSig)(handle, redirectTo, context, provider, contract),
+        natsConnectSigForIat: (iat, contractDigest) => (0, browser_js_1.natsConnectSigForIat)(handle, iat, contractDigest),
+        bootstrapSig: (iat) => signDomainValue((data) => (0, session_js_1.signBytes)(handle, data), "bootstrap-client", String(iat)),
+        bindFlowSig: (flowId) => (0, session_js_1.bindFlowSig)(handle, flowId),
+    };
+}
+async function bindClientFlow(args) {
+    const response = await fetch(`${args.trellisUrl}/auth/flow/${encodeURIComponent(args.flowId)}/bind`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ sessionKey: args.sessionKey, sig: args.sig }),
+    });
+    if (!response.ok) {
+        const reason = await response.text();
+        throw createTransportError({
+            code: "trellis.auth.bind_failed",
+            message: "Trellis could not finish the sign-in step.",
+            hint: "Start the sign-in flow again.",
+            context: { status: response.status, trellisUrl: args.trellisUrl, reason },
+        });
+    }
+    const payload = await readJsonResponse(response, {
+        code: "trellis.auth.bind_invalid_response",
+        message: "Trellis returned an invalid sign-in response.",
+        hint: "Start the sign-in flow again.",
+        context: { flowId: args.flowId },
+    });
+    if (payload && typeof payload === "object" &&
+        payload.status === "expired") {
+        throw createTransportError({
+            code: "trellis.auth.bind_expired",
+            message: "The Trellis sign-in step expired.",
+            hint: "Start the sign-in flow again.",
+            context: { flowId: args.flowId },
+        });
+    }
+    let parsed;
+    try {
+        parsed = value_1.Value.Parse(browser_js_2.BindResponseSchema, payload);
+    }
+    catch (cause) {
+        throw createTransportError({
+            code: "trellis.auth.bind_invalid_response",
+            message: "Trellis returned an invalid sign-in response.",
+            hint: "Start the sign-in flow again.",
+            cause,
+            context: { flowId: args.flowId },
+        });
+    }
+    if (parsed.status !== "bound") {
+        throw createTransportError({
+            code: "trellis.auth.bind_invalid_response",
+            message: "Trellis returned an invalid sign-in response.",
+            hint: "Start the sign-in flow again.",
+            context: { flowId: args.flowId, status: parsed.status },
+        });
+    }
+}
+async function fetchClientBootstrap(args) {
+    const response = await fetch(`${args.trellisUrl}/bootstrap/client`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            sessionKey: args.sessionKey,
+            iat: args.iat,
+            sig: args.bootstrapSig,
+        }),
+    });
+    const payload = await readJsonResponse(response, {
+        code: "trellis.bootstrap.invalid_response",
+        message: "Trellis returned an invalid bootstrap response.",
+        hint: "Retry the connection. If it keeps happening, check the Trellis deployment.",
+        context: { trellisUrl: args.trellisUrl },
+    });
+    if (!response.ok) {
+        if (value_1.Value.Check(ClientBootstrapIatOutOfRangeSchema, payload)) {
+            return payload;
+        }
+        const reason = payload && typeof payload === "object" &&
+            typeof payload.reason === "string"
+            ? payload.reason
+            : `http_${response.status}`;
+        throw createTransportError({
+            code: "trellis.bootstrap.failed",
+            message: "Trellis could not prepare the client session.",
+            hint: "Retry the connection. If it keeps failing, check Trellis availability and access.",
+            context: { trellisUrl: args.trellisUrl, status: response.status, reason },
+        });
+    }
+    if (value_1.Value.Check(ClientBootstrapReadySchema, payload)) {
+        return payload;
+    }
+    if (value_1.Value.Check(ClientBootstrapAuthRequiredSchema, payload)) {
+        return payload;
+    }
+    if (value_1.Value.Check(ClientBootstrapNotReadySchema, payload)) {
+        return payload;
+    }
+    throw createTransportError({
+        code: "trellis.bootstrap.invalid_response",
+        message: "Trellis returned an invalid bootstrap response.",
+        hint: "Retry the connection. If it keeps happening, check the Trellis deployment.",
+        context: { trellisUrl: args.trellisUrl },
+    });
+}
+function updateClockOffsetFromServer(args) {
+    args.offsetState.serverClockOffsetMs = (0, time_js_1.estimateMidpointClockOffsetMs)({
+        requestStartedAtMs: args.requestStartedAtMs,
+        responseReceivedAtMs: args.responseReceivedAtMs,
+        serverNowSeconds: args.serverNowSeconds,
+    });
+}
+async function fetchClientBootstrapWithRetry(args) {
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        const requestStartedAtMs = args.deps.now();
+        const iat = (0, time_js_1.correctedIatSeconds)(requestStartedAtMs, args.offsetState.serverClockOffsetMs);
+        const response = await fetchClientBootstrap({
+            trellisUrl: args.trellisUrl,
+            sessionKey: args.sessionKey,
+            iat,
+            bootstrapSig: await args.identity.bootstrapSig(iat),
+        });
+        const responseReceivedAtMs = args.deps.now();
+        updateClockOffsetFromServer({
+            offsetState: args.offsetState,
+            requestStartedAtMs,
+            responseReceivedAtMs,
+            serverNowSeconds: response.serverNow,
+        });
+        if ("status" in response) {
+            return response;
+        }
+    }
+    throw createTransportError({
+        code: "trellis.bootstrap.time_sync_failed",
+        message: "Trellis could not confirm the client time window.",
+        hint: "Retry the connection. If it keeps happening, check the client and Trellis clocks.",
+        context: { trellisUrl: args.trellisUrl },
+    });
+}
+async function createRuntimeUserAuthenticator(args) {
+    const browserTokenLookaheadSeconds = 300;
+    const jwtAuth = (nonce) => {
+        const sentinel = args.getSentinel();
+        return (0, nats_core_1.jwtAuthenticator)(sentinel.jwt, new TextEncoder().encode(sentinel.seed))(nonce);
+    };
+    if (args.identity.buildRuntimeAuthTokenSync) {
+        return {
+            authenticators: [
+                jwtAuth,
+                () => ({
+                    auth_token: args.identity.buildRuntimeAuthTokenSync((0, time_js_1.correctedIatSeconds)(args.deps.now(), args.offsetState.serverClockOffsetMs), args.getContractDigest()),
+                }),
+            ],
+            stop: () => { },
+        };
+    }
+    const buildRuntimeAuthToken = async (iat) => {
+        return JSON.stringify({
+            v: 1,
+            sessionKey: args.identity.sessionKey,
+            iat,
+            contractDigest: args.getContractDigest(),
+            sig: await args.identity.natsConnectSigForIat(iat, args.getContractDigest()),
+        });
+    };
+    let currentToken = await buildRuntimeAuthToken((0, time_js_1.correctedIatSeconds)(args.deps.now(), args.offsetState.serverClockOffsetMs));
+    const precomputedTokens = new Map();
+    let latestPreparedIat = 0;
+    let refreshInFlight = null;
+    let recoveryInFlight = null;
+    const refresh = () => {
+        if (refreshInFlight)
+            return refreshInFlight;
+        refreshInFlight = (async () => {
+            const currentIat = (0, time_js_1.correctedIatSeconds)(args.deps.now(), args.offsetState.serverClockOffsetMs);
+            const maxIat = currentIat + browserTokenLookaheadSeconds;
+            const startIat = Math.max(currentIat, latestPreparedIat + 1);
+            for (let iat = startIat; iat <= maxIat; iat += 1) {
+                precomputedTokens.set(iat, await buildRuntimeAuthToken(iat));
+            }
+            latestPreparedIat = Math.max(latestPreparedIat, maxIat);
+            for (const iat of precomputedTokens.keys()) {
+                if (iat < currentIat - 5) {
+                    precomputedTokens.delete(iat);
+                }
+            }
+            const nextToken = precomputedTokens.get(currentIat);
+            if (nextToken) {
+                currentToken = nextToken;
+            }
+        })().finally(() => {
+            refreshInFlight = null;
+        });
+        return refreshInFlight;
+    };
+    const recover = () => {
+        if (!args.recoverBrowserAuth) {
+            return Promise.resolve();
+        }
+        if (recoveryInFlight)
+            return recoveryInFlight;
+        recoveryInFlight = (async () => {
+            const digestBefore = args.getContractDigest();
+            await args.recoverBrowserAuth?.();
+            if (args.getContractDigest() !== digestBefore) {
+                precomputedTokens.clear();
+                latestPreparedIat = 0;
+            }
+            await refresh();
+        })().finally(() => {
+            recoveryInFlight = null;
+        });
+        return recoveryInFlight;
+    };
+    await refresh();
+    const setRefreshInterval = args.deps.setInterval ??
+        ((handler, ms) => globalThis.setInterval(handler, ms));
+    const clearRefreshInterval = args.deps.clearInterval ??
+        ((id) => globalThis.clearInterval(id));
+    const refreshIntervalId = setRefreshInterval(() => {
+        void refresh();
+    }, 10_000);
+    return {
+        authenticators: [
+            jwtAuth,
+            () => {
+                const currentIat = (0, time_js_1.correctedIatSeconds)(args.deps.now(), args.offsetState.serverClockOffsetMs);
+                const nextToken = precomputedTokens.get(currentIat);
+                if (nextToken) {
+                    currentToken = nextToken;
+                    if (currentIat >= latestPreparedIat - 60) {
+                        void refresh();
+                    }
+                    return { auth_token: currentToken };
+                }
+                if (args.recoverBrowserAuth) {
+                    void recover();
+                    return { auth_token: currentToken };
+                }
+                void refresh();
+                return { auth_token: currentToken };
+            },
+        ],
+        stop: () => {
+            clearRefreshInterval(refreshIntervalId);
+        },
+    };
+}
+function cleanupBrowserCallbackUrl(currentUrl) {
+    if (!isBrowserRuntime())
+        return;
+    if (!currentUrl.searchParams.has("flowId") &&
+        !currentUrl.searchParams.has("authError")) {
+        return;
+    }
+    currentUrl.searchParams.delete("flowId");
+    currentUrl.searchParams.delete("authError");
+    globalThis.history.replaceState({}, "", currentUrl.pathname + currentUrl.search + currentUrl.hash);
+}
+function isExpiredBindError(error) {
+    return error instanceof index_js_1.TransportError &&
+        error.code === "trellis.auth.bind_expired";
+}
+function needsReauth(bootstrap) {
+    return bootstrap.status === "auth_required" ||
+        (bootstrap.status === "not_ready" &&
+            (bootstrap.reason === "insufficient_permissions" ||
+                bootstrap.reason === "contract_not_active"));
+}
+function bootstrapTargetsRequestedContract(bootstrap, args) {
+    const requestedDigest = args.contract.CONTRACT_DIGEST ??
+        (0, mod_js_1.digestContractManifest)(args.contract.CONTRACT);
+    return bootstrap.status === "ready" &&
+        bootstrap.connectInfo.contractId === args.contract.CONTRACT.id &&
+        bootstrap.connectInfo.contractDigest === requestedDigest;
+}
+async function buildSessionKeyLoginUrl(args) {
+    const context = authRequestContextRecord(args.context);
+    const response = await fetch(`${args.trellisUrl}/auth/requests`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            redirectTo: args.redirectTo,
+            sessionKey: args.sessionKey,
+            sig: args.oauthInitSig,
+            contract: args.contract,
+            ...(args.provider ? { provider: args.provider } : {}),
+            ...(context ? { context } : {}),
+        }),
+    });
+    if (!response.ok) {
+        const reason = await response.text();
+        throw createTransportError({
+            code: "trellis.auth.login_failed",
+            message: "Trellis could not start sign-in.",
+            hint: "Retry sign-in. If it keeps failing, check Trellis availability and access.",
+            context: { status: response.status, reason, trellisUrl: args.trellisUrl },
+        });
+    }
+    const payload = await readJsonResponse(response, {
+        code: "trellis.auth.login_invalid_response",
+        message: "Trellis returned an invalid sign-in response.",
+        hint: "Retry sign-in. If it keeps happening, start the sign-in flow again.",
+        context: { trellisUrl: args.trellisUrl },
+    });
+    if (payload && typeof payload === "object" &&
+        payload.status === "flow_started" &&
+        typeof payload.loginUrl === "string") {
+        return {
+            status: "flow_started",
+            loginUrl: payload.loginUrl,
+        };
+    }
+    if (payload && typeof payload === "object" &&
+        payload.status === "bound") {
+        return { status: "bound" };
+    }
+    throw createTransportError({
+        code: "trellis.auth.login_invalid_response",
+        message: "Trellis returned an invalid sign-in response.",
+        hint: "Retry sign-in. If it keeps happening, start the sign-in flow again.",
+        context: { trellisUrl: args.trellisUrl },
+    });
+}
+async function connectClientWithDeps(args, deps) {
+    const trellisUrl = normalizeTrellisUrl(args.trellisUrl);
+    const identity = await resolveClientIdentity(args.auth);
+    const currentUrl = args.auth?.mode === "session_key"
+        ? null
+        : resolveCurrentUrl(args.auth);
+    const browserAuth = args.auth?.mode === "session_key" ? undefined : args.auth;
+    const callbackFlowId = args.auth?.mode === "session_key"
+        ? args.auth.flowId
+        : browserAuth?.flowId ?? currentUrl?.searchParams.get("flowId") ??
+            undefined;
+    const offsetState = { serverClockOffsetMs: 0 };
+    if (callbackFlowId) {
+        try {
+            await bindClientFlow({
+                trellisUrl,
+                sessionKey: identity.sessionKey,
+                flowId: callbackFlowId,
+                sig: await identity.bindFlowSig(callbackFlowId),
+            });
+            if (currentUrl)
+                cleanupBrowserCallbackUrl(currentUrl);
+        }
+        catch (error) {
+            if (currentUrl && isExpiredBindError(error)) {
+                cleanupBrowserCallbackUrl(currentUrl);
+            }
+            throw error;
+        }
+    }
+    const initialBootstrap = await fetchClientBootstrapWithRetry({
+        trellisUrl,
+        sessionKey: identity.sessionKey,
+        identity,
+        deps,
+        offsetState,
+    });
+    const bootstrap = needsReauth(initialBootstrap) ||
+        !bootstrapTargetsRequestedContract(initialBootstrap, args)
+        ? await resolveAuthRequired(args, identity, currentUrl, deps, offsetState)
+        : initialBootstrap;
+    if (bootstrap.status !== "ready") {
+        if (bootstrap.status === "not_ready") {
+            throw createTransportError({
+                code: "trellis.bootstrap.not_ready",
+                message: "Trellis is not ready to connect this client.",
+                hint: "Wait for the requested app access to become available, then try again.",
+                context: { reason: bootstrap.reason },
+            });
+        }
+        throw createTransportError({
+            code: "trellis.bootstrap.auth_required",
+            message: "Trellis still requires sign-in before connecting this client.",
+            hint: "Complete sign-in, then try again.",
+        });
+    }
+    const transport = await deps.loadTransport();
+    const runtimeState = {
+        contractDigest: bootstrap.connectInfo.contractDigest,
+        sentinel: bootstrap.connectInfo.transport.sentinel,
+    };
+    const recoverBrowserAuth = identity.mode === "browser"
+        ? async () => {
+            const latestCurrentUrl = resolveCurrentUrl(browserAuth);
+            const refreshedBootstrap = await fetchClientBootstrapWithRetry({
+                trellisUrl,
+                sessionKey: identity.sessionKey,
+                identity,
+                deps,
+                offsetState,
+            });
+            const resolvedBootstrap = needsReauth(refreshedBootstrap) ||
+                (refreshedBootstrap.status === "ready" &&
+                    !bootstrapTargetsRequestedContract(refreshedBootstrap, args))
+                ? await resolveAuthRequired(args, identity, latestCurrentUrl, deps, offsetState)
+                : refreshedBootstrap;
+            if (resolvedBootstrap.status !== "ready") {
+                if (resolvedBootstrap.status === "not_ready") {
+                    throw createTransportError({
+                        code: "trellis.bootstrap.not_ready",
+                        message: "Trellis is not ready to reconnect this client.",
+                        hint: "Wait for the requested app access to become available, then try again.",
+                        context: { reason: resolvedBootstrap.reason },
+                    });
+                }
+                throw createTransportError({
+                    code: "trellis.bootstrap.auth_required",
+                    message: "Trellis still requires sign-in before reconnecting this client.",
+                    hint: "Complete sign-in, then try again.",
+                });
+            }
+            runtimeState.contractDigest =
+                resolvedBootstrap.connectInfo.contractDigest;
+            runtimeState.sentinel = resolvedBootstrap.connectInfo.transport.sentinel;
+        }
+        : undefined;
+    const handleSessionNotFound = identity.mode === "browser"
+        ? async () => {
+            const latestCurrentUrl = resolveCurrentUrl(browserAuth);
+            try {
+                await resolveAuthRequired(args, identity, latestCurrentUrl, deps, offsetState);
+            }
+            catch (error) {
+                if (error instanceof ClientAuthHandledError) {
+                    return;
+                }
+                throw error;
+            }
+        }
+        : undefined;
+    const runtimeAuth = await createRuntimeUserAuthenticator({
+        identity,
+        deps,
+        offsetState,
+        getContractDigest: () => runtimeState.contractDigest,
+        getSentinel: () => runtimeState.sentinel,
+        recoverBrowserAuth,
+    });
+    let nc;
+    try {
+        nc = await transport.connect({
+            servers: (0, runtime_transport_js_1.selectRuntimeTransportServers)(bootstrap.connectInfo.transports),
+            maxReconnectAttempts: runtime_transport_js_1.DEFAULT_RUNTIME_MAX_RECONNECT_ATTEMPTS,
+            inboxPrefix: bootstrap.connectInfo.transport.inboxPrefix,
+            authenticator: runtimeAuth.authenticators,
+        });
+    }
+    catch (error) {
+        runtimeAuth.stop();
+        throw createTransportError({
+            code: "trellis.runtime.connect_failed",
+            message: "Trellis could not open the runtime connection.",
+            hint: "Retry the connection. If it keeps failing, check Trellis transport availability.",
+            cause: error,
+            context: { trellisUrl },
+        });
+    }
+    void nc.closed().finally(() => runtimeAuth.stop());
+    const clientOpts = {
+        ...(typeof args.name === "string" ? { name: args.name } : {}),
+        ...(args.log ? { log: args.log } : {}),
+        ...(typeof args.timeout === "number" ? { timeout: args.timeout } : {}),
+        ...(typeof args.stream === "string" ? { stream: args.stream } : {}),
+        ...(args.noResponderRetry
+            ? { noResponderRetry: args.noResponderRetry }
+            : {}),
+    };
+    const connection = (0, connection_js_1.observeNatsTrellisConnection)({
+        kind: "client",
+        nc,
+        log: false,
+        ...(args.log
+            ? {
+                lifecycleLog: {
+                    log: args.log,
+                    context: { client: clientOpts.name ?? "client" },
+                },
+            }
+            : {}),
+    });
+    const api = args.contract.API.trellis;
+    const state = args.contract[mod_js_1.CONTRACT_STATE_METADATA];
+    return createConnectedClient({
+        name: clientOpts.name ?? "client",
+        nc,
+        connection,
+        sessionKey: identity.sessionKey,
+        sign: identity.sign,
+        opts: {
+            log: clientOpts.log,
+            timeout: clientOpts.timeout,
+            stream: clientOpts.stream,
+            noResponderRetry: clientOpts.noResponderRetry,
+            api,
+            state,
+            onSessionNotFound: handleSessionNotFound,
+        },
+    });
+}
+async function resolveAuthRequired(args, identity, currentUrl, deps, offsetState) {
+    const browserAuth = args.auth?.mode === "session_key" ? {} : args.auth ?? {};
+    const redirectTo = args.auth?.mode === "session_key"
+        ? args.auth.redirectTo
+        : currentUrl
+            ? resolveRedirectTo(browserAuth, currentUrl)
+            : resolveConfiguredRedirectTo(browserAuth.redirectTo);
+    if (!redirectTo) {
+        throw new Error("Client authentication requires a redirectTo URL");
+    }
+    const authStart = args.auth?.mode === "session_key"
+        ? await buildSessionKeyLoginUrl({
+            trellisUrl: normalizeTrellisUrl(args.trellisUrl),
+            redirectTo,
+            sessionKey: identity.sessionKey,
+            contract: args.contract.CONTRACT,
+            provider: args.auth.provider,
+            context: args.auth.context,
+            oauthInitSig: await identity.oauthInitSig(redirectTo, authRequestContextRecord(args.auth.context), args.auth.provider, args.contract.CONTRACT),
+        })
+        : await (0, browser_js_1.startAuthRequest)({
+            authUrl: normalizeTrellisUrl(args.trellisUrl),
+            redirectTo,
+            handle: browserAuth.handle ?? await (0, browser_js_1.getOrCreateSessionKey)(),
+            provider: browserAuth.provider,
+            contract: args.contract.CONTRACT,
+            context: browserAuth.context,
+        });
+    if (authStart.status === "bound") {
+        return await fetchClientBootstrapWithRetry({
+            trellisUrl: normalizeTrellisUrl(args.trellisUrl),
+            sessionKey: identity.sessionKey,
+            identity,
+            deps,
+            offsetState,
+        });
+    }
+    const loginUrl = authStart.loginUrl;
+    const continuation = await args.onAuthRequired?.({
+        loginUrl,
+        sessionKey: identity.sessionKey,
+        mode: identity.mode,
+    });
+    if (continuation && continuation.status === "handled") {
+        throw new ClientAuthHandledError();
+    }
+    if (continuation && continuation.status === "bound") {
+        await bindClientFlow({
+            trellisUrl: normalizeTrellisUrl(args.trellisUrl),
+            sessionKey: identity.sessionKey,
+            flowId: continuation.flowId,
+            sig: await identity.bindFlowSig(continuation.flowId),
+        });
+        return await fetchClientBootstrapWithRetry({
+            trellisUrl: normalizeTrellisUrl(args.trellisUrl),
+            sessionKey: identity.sessionKey,
+            identity,
+            deps,
+            offsetState,
+        });
+    }
+    if (isBrowserRuntime()) {
+        globalThis.location.href = loginUrl;
+        throw new Error("Redirecting to Trellis login");
+    }
+    throw new Error("Client authentication required and no auth continuation was provided");
+}
+class TrellisClient {
+    static connect(args) {
+        return clientConnectResult(connectClientWithDeps(args, defaultDeps));
+    }
+}
+exports.TrellisClient = TrellisClient;