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

package/esm/client_connect.js

@@ -1,14 +1,43 @@
-import * as dntShim from "./_dnt.shims.js";
-import { jwtAuthenticator } from "@nats-io/nats-core";
-import { getOrCreateSessionKey, getPublicSessionKey, startAuthRequest, } from "./auth/browser.js";
-import { BindResponseSchema, sha256, toArrayBuffer, utf8 } from "./auth/browser.js";
+import { jwtAuthenticator, } from "@nats-io/nats-core";
+import { CONTRACT_STATE_METADATA, digestContractManifest, } from "./contract_support/mod.js";
+import { base64urlDecode, base64urlEncode, getOrCreateSessionKey, getPublicSessionKey, natsConnectSigForIat, startAuthRequest, } from "./auth/browser.js";
+import { BindResponseSchema, sha256, toArrayBuffer, utf8, } from "./auth/browser.js";
+import { correctedIatSeconds, estimateMidpointClockOffsetMs, } from "./auth/time.js";
+import { buildNatsConnectSignaturePayload } from "./auth/session_auth.js";
 import { canonicalizeJsonValue } from "./auth/utils.js";
-import { importEd25519PrivateKeyFromSeedBase64url, publicKeyBase64urlFromPrivateKey, } from "./auth/keys.js";
-import { loadDefaultRuntimeTransport, selectRuntimeTransportServers, } from "./runtime_transport.js";
-import { Trellis } from "./trellis.js";
+import { importEd25519PrivateKeyFromSeedBase64url, publicKeyBase64urlFromSeed, signEd25519SeedSha256, } from "./auth/keys.js";
+import { DEFAULT_RUNTIME_MAX_RECONNECT_ATTEMPTS, loadDefaultRuntimeTransport, selectRuntimeTransportServers, } from "./runtime_transport.js";
+import { Trellis, } from "./trellis.js";
+import { TransportError } from "./errors/index.js";
+import { AsyncResult, Result, UnexpectedError } from "@qlever-llc/result";
 import { Type } from "typebox";
 import { Value } from "typebox/value";
 import { bindFlowSig, oauthInitSig, signBytes, } from "./auth/browser/session.js";
+import { observeNatsTrellisConnection, } from "./connection.js";
+function createConnectedClient(args) {
+    const trellis = new Trellis(args.name, args.nc, {
+        sessionKey: args.sessionKey,
+        sign: args.sign,
+    }, {
+        ...args.opts,
+        connection: args.connection,
+    });
+    return trellis;
+}
+function clientConnectResult(promise) {
+    return AsyncResult.from(promise.then((value) => Result.ok(value), (cause) => Result.err(cause instanceof TransportError
+        ? cause
+        : new UnexpectedError({ cause }))));
+}
+/**
+ * Error raised when client authentication was delegated to caller-owned routing.
+ */
+export class ClientAuthHandledError extends Error {
+    constructor() {
+        super("Client authentication was handled by the caller");
+        this.name = "ClientAuthHandledError";
+    }
+}
 const ClientTransportEndpointsSchema = Type.Object({
     natsServers: Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }),
 });
@@ -18,6 +47,7 @@ const ClientTransportsSchema = Type.Object({
 });
 const ClientBootstrapReadySchema = Type.Object({
     status: Type.Literal("ready"),
+    serverNow: Type.Integer(),
     connectInfo: Type.Object({
         sessionKey: Type.String({ minLength: 1 }),
         contractId: Type.String({ minLength: 1 }),
@@ -30,42 +60,78 @@ const ClientBootstrapReadySchema = Type.Object({
                 seed: Type.String({ minLength: 1 }),
             }),
         }),
-        auth: Type.Object({
-            mode: Type.Literal("binding_token"),
-            bindingToken: Type.String({ minLength: 1 }),
-            expiresAt: Type.String({ format: "date-time" }),
-        }),
     }),
 }, { additionalProperties: true });
 const ClientBootstrapAuthRequiredSchema = Type.Object({
     status: Type.Literal("auth_required"),
+    serverNow: Type.Integer(),
 }, { additionalProperties: true });
 const ClientBootstrapNotReadySchema = Type.Object({
     status: Type.Literal("not_ready"),
     reason: Type.String({ minLength: 1 }),
+    serverNow: Type.Integer(),
+}, { additionalProperties: true });
+const ClientBootstrapIatOutOfRangeSchema = Type.Object({
+    reason: Type.Literal("iat_out_of_range"),
+    serverNow: Type.Integer(),
 }, { additionalProperties: true });
 function isBrowserRuntime() {
-    return typeof dntShim.dntGlobalThis !== "undefined" && typeof document !== "undefined";
+    return typeof window !== "undefined" && typeof document !== "undefined";
 }
 const defaultDeps = {
     loadTransport: 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 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) {
-    if (auth?.currentUrl instanceof URL)
-        return auth.currentUrl;
-    if (typeof auth?.currentUrl === "string")
-        return new URL(auth.currentUrl);
-    if (isBrowserRuntime())
-        return new URL(globalThis.location.href);
+    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) {
-    if (auth.redirectTo) {
-        return new URL(auth.redirectTo, currentUrl.origin).toString();
+    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) {
@@ -76,6 +142,15 @@ function resolveRedirectTo(auth, currentUrl) {
     }
     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 sha256(utf8(`${prefix}:${value}`));
     const signature = await sign(digest);
@@ -83,8 +158,9 @@ async function signDomainValue(sign, prefix, value) {
     return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
 }
 async function createSessionKeyRuntimeIdentity(sessionKeySeed) {
+    const seed = base64urlDecode(sessionKeySeed);
     const privateKey = await importEd25519PrivateKeyFromSeedBase64url(sessionKeySeed);
-    const sessionKey = await publicKeyBase64urlFromPrivateKey(privateKey);
+    const sessionKey = publicKeyBase64urlFromSeed(seed);
     const sign = async (data) => {
         const signature = await crypto.subtle.sign("Ed25519", privateKey, toArrayBuffer(data));
         return new Uint8Array(signature);
@@ -93,10 +169,22 @@ async function createSessionKeyRuntimeIdentity(sessionKeySeed) {
         mode: "session_key",
         sessionKey,
         sign,
-        oauthInitSig: (redirectTo, context) => signDomainValue(sign, "oauth-init", `${redirectTo}:${canonicalizeJsonValue(context ?? null)}`),
-        bindingTokenSig: (bindingToken) => signDomainValue(sign, "nats-connect", bindingToken),
+        oauthInitSig: (redirectTo, context, provider, contract) => signDomainValue(sign, "oauth-init", contract === undefined
+            ? `${redirectTo}:${canonicalizeJsonValue(context ?? null)}`
+            : `${redirectTo}:${provider ?? ""}:${canonicalizeJsonValue(contract)}:${canonicalizeJsonValue(context ?? null)}`),
+        natsConnectSigForIat: (iat, contractDigest) => signDomainValue(sign, "nats-connect", buildNatsConnectSignaturePayload(iat, contractDigest)),
         bootstrapSig: (iat) => signDomainValue(sign, "bootstrap-client", String(iat)),
         bindFlowSig: (flowId) => signDomainValue(sign, "bind-flow", flowId),
+        buildRuntimeAuthTokenSync: (iat, contractDigest) => {
+            const sig = signEd25519SeedSha256(seed, utf8(`nats-connect:${buildNatsConnectSignaturePayload(iat, contractDigest)}`));
+            return JSON.stringify({
+                v: 1,
+                sessionKey,
+                iat,
+                contractDigest,
+                sig: base64urlEncode(new Uint8Array(sig)),
+            });
+        },
     };
 }
 async function resolveClientIdentity(auth) {
@@ -108,8 +196,8 @@ async function resolveClientIdentity(auth) {
         mode: "browser",
         sessionKey: getPublicSessionKey(handle),
         sign: (data) => signBytes(handle, data),
-        oauthInitSig: (redirectTo, context) => oauthInitSig(handle, redirectTo, context),
-        bindingTokenSig: (bindingToken) => signDomainValue((data) => signBytes(handle, data), "nats-connect", bindingToken),
+        oauthInitSig: (redirectTo, context, provider, contract) => oauthInitSig(handle, redirectTo, context, provider, contract),
+        natsConnectSigForIat: (iat, contractDigest) => natsConnectSigForIat(handle, iat, contractDigest),
         bootstrapSig: (iat) => signDomainValue((data) => signBytes(handle, data), "bootstrap-client", String(iat)),
         bindFlowSig: (flowId) => bindFlowSig(handle, flowId),
     };
@@ -121,16 +209,53 @@ async function bindClientFlow(args) {
         body: JSON.stringify({ sessionKey: args.sessionKey, sig: args.sig }),
     });
     if (!response.ok) {
-        throw new Error(`Client bind failed: ${response.status} ${await response.text()}`);
+        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.Parse(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 },
+        });
     }
-    const payload = await response.json();
-    const parsed = Value.Parse(BindResponseSchema, payload);
     if (parsed.status !== "bound") {
-        throw new Error(`Client bind did not complete: ${parsed.status}`);
+        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(new URL("/bootstrap/client", args.trellisUrl), {
+    const response = await fetch(`${args.trellisUrl}/bootstrap/client`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({
@@ -139,12 +264,26 @@ async function fetchClientBootstrap(args) {
             sig: args.bootstrapSig,
         }),
     });
-    const payload = await response.json();
+    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) {
-        const reason = typeof payload?.reason === "string"
+        if (Value.Check(ClientBootstrapIatOutOfRangeSchema, payload)) {
+            return payload;
+        }
+        const reason = payload && typeof payload === "object" &&
+            typeof payload.reason === "string"
             ? payload.reason
             : `http_${response.status}`;
-        throw new Error(`Client bootstrap failed: ${reason}`);
+        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.Check(ClientBootstrapReadySchema, payload)) {
         return payload;
@@ -155,23 +294,187 @@ async function fetchClientBootstrap(args) {
     if (Value.Check(ClientBootstrapNotReadySchema, payload)) {
         return payload;
     }
-    throw new Error("Client bootstrap returned an invalid response");
+    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 = 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 = 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 jwtAuthenticator(sentinel.jwt, new TextEncoder().encode(sentinel.seed))(nonce);
+    };
+    if (args.identity.buildRuntimeAuthTokenSync) {
+        return {
+            authenticators: [
+                jwtAuth,
+                () => ({
+                    auth_token: args.identity.buildRuntimeAuthTokenSync(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(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 = 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 = 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")) {
+    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);
+    window.history.replaceState({}, "", currentUrl.pathname + currentUrl.search + currentUrl.hash);
+}
+function isExpiredBindError(error) {
+    return error instanceof TransportError &&
+        error.code === "trellis.auth.bind_expired";
 }
 function needsReauth(bootstrap) {
     return bootstrap.status === "auth_required" ||
-        (bootstrap.status === "not_ready" && bootstrap.reason === "insufficient_permissions");
+        (bootstrap.status === "not_ready" &&
+            (bootstrap.reason === "insufficient_permissions" ||
+                bootstrap.reason === "contract_not_active"));
+}
+function bootstrapTargetsRequestedContract(bootstrap, args) {
+    const requestedDigest = args.contract.CONTRACT_DIGEST ??
+        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" },
@@ -181,99 +484,229 @@ async function buildSessionKeyLoginUrl(args) {
             sig: args.oauthInitSig,
             contract: args.contract,
             ...(args.provider ? { provider: args.provider } : {}),
-            ...(args.context && typeof args.context === "object" && !Array.isArray(args.context)
-                ? { context: args.context }
-                : {}),
+            ...(context ? { context } : {}),
         }),
     });
     if (!response.ok) {
         const reason = await response.text();
-        throw new Error(`Login flow creation failed: ${response.status} ${reason}`);
+        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 response.json();
+    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 };
+        return {
+            status: "flow_started",
+            loginUrl: payload.loginUrl,
+        };
     }
-    if (payload && typeof payload === "object" && payload.status === "bound") {
+    if (payload && typeof payload === "object" &&
+        payload.status === "bound") {
         return { status: "bound" };
     }
-    throw new Error("Login flow creation returned an invalid response");
+    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 },
+    });
 }
 export 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 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
-        : currentUrl?.searchParams.get("flowId") ?? undefined;
+        : browserAuth?.flowId ?? currentUrl?.searchParams.get("flowId") ??
+            undefined;
+    const offsetState = { serverClockOffsetMs: 0 };
     if (callbackFlowId) {
-        await bindClientFlow({
-            trellisUrl,
-            sessionKey: identity.sessionKey,
-            flowId: callbackFlowId,
-            sig: await identity.bindFlowSig(callbackFlowId),
-        });
-        if (currentUrl)
-            cleanupBrowserCallbackUrl(currentUrl);
+        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 bootstrapIat = Math.floor(deps.now() / 1_000);
-    const initialBootstrap = await fetchClientBootstrap({
+    const initialBootstrap = await fetchClientBootstrapWithRetry({
         trellisUrl,
         sessionKey: identity.sessionKey,
-        iat: bootstrapIat,
-        bootstrapSig: await identity.bootstrapSig(bootstrapIat),
+        identity,
+        deps,
+        offsetState,
     });
-    const bootstrap = needsReauth(initialBootstrap)
-        ? await resolveAuthRequired(args, identity, currentUrl, deps)
+    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 new Error(`Client bootstrap is not ready: ${bootstrap.reason}`);
+            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 new Error("Client bootstrap still requires authentication");
+        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 token = JSON.stringify({
-        v: 1,
-        sessionKey: identity.sessionKey,
-        bindingToken: bootstrap.connectInfo.auth.bindingToken,
-        sig: await identity.bindingTokenSig(bootstrap.connectInfo.auth.bindingToken),
-    });
-    const nc = await transport.connect({
-        servers: selectRuntimeTransportServers(bootstrap.connectInfo.transports),
-        token,
-        inboxPrefix: bootstrap.connectInfo.transport.inboxPrefix,
-        authenticator: jwtAuthenticator(bootstrap.connectInfo.transport.sentinel.jwt, new TextEncoder().encode(bootstrap.connectInfo.transport.sentinel.seed)),
+    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: selectRuntimeTransportServers(bootstrap.connectInfo.transports),
+            maxReconnectAttempts: 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 } : {}),
+        ...(args.noResponderRetry
+            ? { noResponderRetry: args.noResponderRetry }
+            : {}),
     };
-    return new Trellis(clientOpts.name ?? "client", nc, {
+    const connection = 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[CONTRACT_STATE_METADATA];
+    return createConnectedClient({
+        name: clientOpts.name ?? "client",
+        nc,
+        connection,
         sessionKey: identity.sessionKey,
         sign: identity.sign,
-    }, {
-        log: clientOpts.log,
-        timeout: clientOpts.timeout,
-        stream: clientOpts.stream,
-        noResponderRetry: clientOpts.noResponderRetry,
-        api: args.contract.API.trellis,
+        opts: {
+            log: clientOpts.log,
+            timeout: clientOpts.timeout,
+            stream: clientOpts.stream,
+            noResponderRetry: clientOpts.noResponderRetry,
+            api,
+            state,
+            onSessionNotFound: handleSessionNotFound,
+        },
     });
 }
-async function resolveAuthRequired(args, identity, currentUrl, deps) {
-    const browserAuth = args.auth?.mode === "session_key"
-        ? {}
-        : args.auth ?? {};
+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)
-            : undefined;
+            : resolveConfiguredRedirectTo(browserAuth.redirectTo);
     if (!redirectTo) {
         throw new Error("Client authentication requires a redirectTo URL");
     }
@@ -285,7 +718,7 @@ async function resolveAuthRequired(args, identity, currentUrl, deps) {
             contract: args.contract.CONTRACT,
             provider: args.auth.provider,
             context: args.auth.context,
-            oauthInitSig: await identity.oauthInitSig(redirectTo, args.auth.context),
+            oauthInitSig: await identity.oauthInitSig(redirectTo, authRequestContextRecord(args.auth.context), args.auth.provider, args.contract.CONTRACT),
         })
         : await startAuthRequest({
             authUrl: normalizeTrellisUrl(args.trellisUrl),
@@ -296,12 +729,12 @@ async function resolveAuthRequired(args, identity, currentUrl, deps) {
             context: browserAuth.context,
         });
     if (authStart.status === "bound") {
-        const bootstrapIat = Math.floor(deps.now() / 1_000);
-        return await fetchClientBootstrap({
+        return await fetchClientBootstrapWithRetry({
             trellisUrl: normalizeTrellisUrl(args.trellisUrl),
             sessionKey: identity.sessionKey,
-            iat: bootstrapIat,
-            bootstrapSig: await identity.bootstrapSig(bootstrapIat),
+            identity,
+            deps,
+            offsetState,
         });
     }
     const loginUrl = authStart.loginUrl;
@@ -310,29 +743,32 @@ async function resolveAuthRequired(args, identity, currentUrl, deps) {
         sessionKey: identity.sessionKey,
         mode: identity.mode,
     });
-    if (continuation && typeof continuation === "object" && "flowId" in continuation) {
+    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),
         });
-        const bootstrapIat = Math.floor(deps.now() / 1_000);
-        return await fetchClientBootstrap({
+        return await fetchClientBootstrapWithRetry({
             trellisUrl: normalizeTrellisUrl(args.trellisUrl),
             sessionKey: identity.sessionKey,
-            iat: bootstrapIat,
-            bootstrapSig: await identity.bootstrapSig(bootstrapIat),
+            identity,
+            deps,
+            offsetState,
         });
     }
     if (isBrowserRuntime()) {
-        globalThis.location.href = loginUrl;
+        window.location.href = loginUrl;
         throw new Error("Redirecting to Trellis login");
     }
     throw new Error("Client authentication required and no auth continuation was provided");
 }
 export class TrellisClient {
     static connect(args) {
-        return connectClientWithDeps(args, defaultDeps);
+        return clientConnectResult(connectClientWithDeps(args, defaultDeps));
     }
 }