@qlever-llc/trellis-svelte 0.4.0

package/README.md

@@ -0,0 +1,7 @@
+# @qlever-llc/trellis-svelte
+
+Svelte integration for Trellis browser applications.
+
+Provides `TrellisProvider` for app-level wiring, along with reactive helpers for auth state, NATS connection state, and Trellis client state.
+
+Uses the contract/runtime model from `@qlever-llc/trellis-contracts` and `@qlever-llc/trellis-trellis`.

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@qlever-llc/trellis-svelte",
+  "version": "0.4.0",
+  "type": "module",
+  "description": "Svelte components and state helpers for Trellis browser applications.",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "svelte": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@nats-io/nats-core": "^3.3.1",
+    "@qlever-llc/trellis-auth": "^0.4.0",
+    "@qlever-llc/trellis-contracts": "^0.4.0",
+    "@qlever-llc/trellis-result": "^0.4.0",
+    "@qlever-llc/trellis-sdk-auth": "^0.4.0",
+    "@qlever-llc/trellis-trellis": "^0.4.0",
+    "typebox": "^1.0.15"
+  },
+  "peerDependencies": {
+    "svelte": "^5.0.0"
+  },
+  "svelte": "./src/index.ts"
+}

package/src/components/TrellisProvider.svelte

@@ -0,0 +1,166 @@
+<script lang="ts">
+  import type { NatsConnection } from "@nats-io/nats-core";
+  import { AsyncResult } from "@qlever-llc/trellis-result";
+  import type { Snippet } from "svelte";
+  import { onDestroy } from "svelte";
+  import {
+    setAuthContext,
+    setNatsStateContext,
+    setTrellisContext,
+  } from "../context.svelte.ts";
+  import { type AuthState, createAuthState } from "../state/auth.svelte.ts";
+  import { createNatsState, type NatsState } from "../state/nats.svelte.ts";
+  import {
+    createTrellisState,
+    type TrellisClientContract,
+    type TrellisState,
+  } from "../state/trellis.svelte.ts";
+
+  type Props = {
+    children: Snippet;
+    loading?: Snippet;
+    authUrl: string;
+    natsServers: string[];
+    serviceName?: string;
+    contract?: TrellisClientContract;
+    loginPath?: string;
+    onAuthExpired?: () => void;
+    onAuthFailed?: (error: unknown) => void;
+    onAuthRequired?: (redirectTo: string) => void;
+    onNatsConnecting?: () => void;
+    onNatsConnected?: () => void;
+    onNatsDisconnect?: () => void;
+    onNatsReconnecting?: () => void;
+    onNatsReconnect?: () => void;
+    onNatsError?: (error: Error) => void;
+  };
+
+  const {
+    children,
+    loading,
+    authUrl,
+    natsServers,
+    serviceName = "app",
+    contract,
+    loginPath = "/login",
+    onAuthExpired,
+    onAuthFailed,
+    onAuthRequired,
+    onNatsConnecting,
+    onNatsConnected,
+    onNatsDisconnect,
+    onNatsReconnecting,
+    onNatsReconnect,
+    onNatsError,
+  }: Props = $props();
+
+  type InitContext = {
+    auth: AuthState;
+    nats: NatsState;
+    trellis: TrellisState;
+  };
+
+  class AuthRequiredError extends Error {
+    constructor() {
+      super("Authentication required");
+    }
+  }
+
+  function createProviderAuthState(): AuthState {
+    return createAuthState({
+      authUrl,
+      loginPath,
+      contract,
+    });
+  }
+
+  const authState = createProviderAuthState();
+
+  function getRedirectTo(): string {
+    if (typeof window === "undefined") {
+      return "/";
+    }
+
+    return window.location.pathname + window.location.search;
+  }
+
+  async function initialize(): Promise<InitContext> {
+    const result = await AsyncResult.try(async () => {
+      await authState.init();
+      await authState.handleCallback();
+      authState.cleanupCallbackUrl();
+
+      if (!authState.isAuthenticated) {
+        onAuthRequired?.(getRedirectTo());
+        throw new AuthRequiredError();
+      }
+
+      const natsState = await createNatsState(authState, {
+        servers: natsServers,
+        onConnecting: onNatsConnecting,
+        onConnected: onNatsConnected,
+        onDisconnect: onNatsDisconnect,
+        onReconnecting: onNatsReconnecting,
+        onReconnect: onNatsReconnect,
+        onError: onNatsError,
+        onAuthRequired: () => {
+          onAuthRequired?.(getRedirectTo());
+        },
+      });
+
+      const trellisState = await createTrellisState(authState, natsState, {
+        serviceName,
+        contract,
+      });
+
+      return {
+        auth: authState,
+        nats: natsState,
+        trellis: trellisState,
+      };
+    });
+
+    if (result.isErr()) {
+      authState.clearAuth();
+      const error = result.error;
+      if (!(error instanceof AuthRequiredError)) {
+        onAuthFailed?.(error);
+      }
+      throw error;
+    }
+
+    return result.match({
+      ok: (value) => value,
+      err: (error) => {
+        throw error;
+      },
+    });
+  }
+
+  const initPromise = initialize();
+  const natsStatePromise = initPromise.then((ctx) => ctx.nats) as Promise<NatsState>;
+  const trellisPromise = initPromise.then((ctx) => ctx.trellis.trellis) as Promise<unknown>;
+  const natsPromise = initPromise.then((ctx) => ctx.nats.nc) as Promise<NatsConnection>;
+
+  setAuthContext(authState);
+  setNatsStateContext(natsStatePromise);
+  setTrellisContext({
+    trellis: trellisPromise as never,
+    nats: natsPromise,
+  });
+
+  onDestroy(() => {
+    void initPromise.then((ctx) => {
+      ctx.trellis.stop();
+      void ctx.nats.disconnect();
+    });
+  });
+</script>
+
+{#await initPromise}
+  {#if loading}
+    {@render loading()}
+  {/if}
+{:then}
+  {@render children()}
+{/await}

package/src/context.svelte.ts

@@ -0,0 +1,47 @@
+import { getContext, setContext } from "svelte";
+import type { TrellisAPI } from "@qlever-llc/trellis-contracts";
+import type { Trellis } from "@qlever-llc/trellis-trellis";
+import type { NatsConnection } from "@nats-io/nats-core";
+import type { AuthState } from "./state/auth.svelte.ts";
+import type { NatsState } from "./state/nats.svelte.ts";
+
+const TRELLIS_KEY = Symbol("trellis");
+const NATS_KEY = Symbol("nats");
+const NATS_STATE_KEY = Symbol("nats-state");
+const AUTH_KEY = Symbol("auth");
+
+type TrellisContext = {
+  trellis: Promise<unknown>;
+  nats: Promise<NatsConnection>;
+};
+
+export function setTrellisContext<TA extends TrellisAPI>(
+  ctx: { trellis: Promise<Trellis<TA>>; nats: Promise<NatsConnection> },
+): void {
+  setContext(TRELLIS_KEY, ctx.trellis as unknown as Promise<unknown>);
+  setContext(NATS_KEY, ctx.nats);
+}
+
+export function setNatsStateContext(natsState: Promise<NatsState>): void {
+  setContext(NATS_STATE_KEY, natsState);
+}
+
+export function setAuthContext(auth: AuthState): void {
+  setContext(AUTH_KEY, auth);
+}
+
+export function getTrellis<TA extends TrellisAPI = TrellisAPI>(): Promise<Trellis<TA>> {
+  return getContext<Promise<unknown>>(TRELLIS_KEY) as Promise<Trellis<TA>>;
+}
+
+export function getNats(): Promise<NatsConnection> {
+  return getContext<Promise<NatsConnection>>(NATS_KEY);
+}
+
+export function getNatsState(): Promise<NatsState> {
+  return getContext<Promise<NatsState>>(NATS_STATE_KEY);
+}
+
+export function getAuth(): AuthState {
+  return getContext<AuthState>(AUTH_KEY);
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export { default as TrellisProvider } from "./components/TrellisProvider.svelte";
+export { setTrellisContext, getTrellis, getNats, getNatsState, getAuth } from "./context.svelte.ts";
+export { AuthState, createAuthState } from "./state/auth.svelte.ts";
+export { NatsState, createNatsState } from "./state/nats.svelte.ts";
+export type { Status as NatsStatus, NatsStateConfig } from "./state/nats.svelte.ts";
+export { TrellisState, createTrellisState } from "./state/trellis.svelte.ts";

package/src/state/auth.svelte.ts

@@ -0,0 +1,297 @@
+import {
+  type BindResponse,
+  type BindSuccessResponse,
+  bindSession,
+  buildLoginUrl,
+  clearSessionKey,
+  extractAuthTokenFromFragment,
+  getOrCreateSessionKey,
+  getPublicSessionKey,
+  type SentinelCreds,
+  type SessionKeyHandle,
+} from "@qlever-llc/trellis-auth";
+import { Result } from "@qlever-llc/trellis-result";
+import { SvelteDate } from "svelte/reactivity";
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+
+const STORAGE_KEY = "trellis_auth";
+
+type AuthStateData = {
+  handle: SessionKeyHandle | null;
+  bindingToken: string | null;
+  inboxPrefix: string | null;
+  expiresMs: number | null;
+  sentinel: SentinelCreds | null;
+};
+
+type PersistedAuth = {
+  bindingToken: string;
+  inboxPrefix: string;
+  expires: string;
+  sentinel: SentinelCreds;
+};
+
+const PersistedAuthSchema = Type.Object({
+  bindingToken: Type.String(),
+  inboxPrefix: Type.String(),
+  expires: Type.String({ format: "date-time" }),
+  sentinel: Type.Object({
+    jwt: Type.String(),
+    seed: Type.String(),
+  }, { additionalProperties: false }),
+}, { additionalProperties: false });
+
+function loadPersistedAuth(): PersistedAuth | null {
+  if (typeof localStorage === "undefined") return null;
+  const result = Result.try(() => {
+    const stored = localStorage.getItem(STORAGE_KEY);
+    if (!stored) return null;
+    const parsed = Value.Parse(PersistedAuthSchema, JSON.parse(stored)) as PersistedAuth;
+    if (new Date(parsed.expires) < new Date()) {
+      localStorage.removeItem(STORAGE_KEY);
+      return null;
+    }
+    if (!parsed.sentinel) return null;
+    return parsed;
+  });
+  return result.unwrapOr(null);
+}
+
+function persistAuth(state: {
+  bindingToken: string;
+  expires: Date;
+  inboxPrefix: string;
+  sentinel: SentinelCreds;
+}): void {
+  if (typeof localStorage === "undefined") return;
+  localStorage.setItem(
+    STORAGE_KEY,
+    JSON.stringify({
+      bindingToken: state.bindingToken,
+      inboxPrefix: state.inboxPrefix,
+      expires: state.expires.toISOString(),
+      sentinel: state.sentinel,
+    }),
+  );
+}
+
+function clearPersistedAuth(): void {
+  if (typeof localStorage === "undefined") return;
+  localStorage.removeItem(STORAGE_KEY);
+}
+
+export type AuthStateConfig = {
+  authUrl: string; // https://auth.example.com
+  loginPath?: string;
+  contract: { CONTRACT: Record<string, unknown> };
+};
+
+/**
+ * Svelte 5 runes-based reactive authentication state.
+ *
+ * Manages session-key based authentication including:
+ * - Session key generation and storage (IndexedDB/WebCrypto)
+ * - OAuth sign-in flow initiation (signed)
+ * - Callback handling (authToken in URL fragment) + bind
+ * - Binding token persistence (short lived)
+ */
+export class AuthState {
+  #state: AuthStateData = $state({
+    handle: null,
+    bindingToken: null,
+    inboxPrefix: null,
+    expiresMs: null,
+    sentinel: null,
+  });
+
+  #config: AuthStateConfig;
+  #bindingInProgress: Promise<BindResponse> | null = null;
+
+  constructor(config: AuthStateConfig) {
+    this.#config = config;
+  }
+
+  get handle(): SessionKeyHandle | null {
+    return this.#state.handle;
+  }
+  get sessionKey(): string | null {
+    return this.#state.handle ? getPublicSessionKey(this.#state.handle) : null;
+  }
+  get bindingToken(): string | null {
+    return this.#state.bindingToken;
+  }
+  get inboxPrefix(): string | null {
+    return this.#state.inboxPrefix;
+  }
+  get expires(): Date | null {
+    return this.#state.expiresMs === null ? null : new SvelteDate(this.#state.expiresMs);
+  }
+  get sentinel(): SentinelCreds | null {
+    return this.#state.sentinel;
+  }
+  get isAuthenticated(): boolean {
+    if (!this.#state.bindingToken) return false;
+    if (this.#state.expiresMs === null) return false;
+    if (!this.#state.sentinel) return false;
+    return this.#state.expiresMs > Date.now();
+  }
+  /**
+   * Initialize the auth state by loading or creating a session key,
+   * and restoring any persisted binding token (if still valid).
+   */
+  async init(): Promise<SessionKeyHandle> {
+    if (this.#state.handle) return this.#state.handle;
+
+    const handle = await getOrCreateSessionKey();
+    this.#state.handle = handle;
+
+    const persisted = loadPersistedAuth();
+    if (persisted) {
+      this.#state.bindingToken = persisted.bindingToken;
+      this.#state.inboxPrefix = persisted.inboxPrefix;
+      this.#state.expiresMs = Date.parse(persisted.expires);
+      this.#state.sentinel = persisted.sentinel;
+    }
+
+    return handle;
+  }
+
+  /**
+   * Initiate OAuth sign-in flow by redirecting to the auth provider.
+   * This method does not return - it redirects the browser.
+   */
+  async signIn(provider: string, redirectTo: string): Promise<never> {
+    const handle = await this.init();
+    const url = await buildLoginUrl(
+      { authUrl: this.#config.authUrl },
+      provider,
+      redirectTo,
+      handle,
+      this.#config.contract.CONTRACT,
+    );
+    window.location.href = url;
+    throw new Error(`Redirecting to ${provider} for authentication`);
+  }
+
+  /**
+   * Handle OAuth callback by extracting the authToken from the URL fragment
+   * and binding it to the session key.
+   *
+   * Returns the bind response if a fragment exists, null otherwise.
+   * Includes a guard to prevent double binding when multiple components call this.
+   */
+  async handleCallback(url: string = window.location.href): Promise<BindResponse | null> {
+    // Guard to prevent race conditions when multiple components call handleCallback
+    if (this.#bindingInProgress) return this.#bindingInProgress;
+
+    const authToken = extractAuthTokenFromFragment(url);
+    if (!authToken) return null;
+
+    this.#bindingInProgress = this.bind(authToken);
+    try {
+      return await this.#bindingInProgress;
+    } finally {
+      this.#bindingInProgress = null;
+    }
+  }
+
+  /**
+   * Clean up the callback URL by removing the authToken fragment.
+   */
+  cleanupCallbackUrl(url: string = window.location.href): void {
+    const parsed = new URL(url);
+    if (parsed.hash) {
+      parsed.hash = "";
+      window.history.replaceState({}, "", parsed.pathname + parsed.search);
+    }
+  }
+
+  /**
+   * Bind an authToken (returned from OAuth callback) to the session key,
+   * producing a short-lived binding token and inboxPrefix for NATS.
+   */
+  async bind(authToken: string): Promise<BindResponse> {
+    return this.#bind(authToken);
+  }
+
+  async #bind(authToken: string): Promise<BindResponse> {
+    const handle = await this.init();
+    const response = await bindSession(
+      { authUrl: this.#config.authUrl },
+      handle,
+      authToken,
+    );
+
+    if (response.status === "bound") {
+      this.setBindingToken(response);
+    }
+
+    return response;
+  }
+
+  setBindingToken(
+    response: Pick<BindSuccessResponse, "bindingToken" | "inboxPrefix" | "expires"> & {
+      sentinel?: SentinelCreds;
+    },
+  ): void {
+    this.#state.bindingToken = response.bindingToken;
+    this.#state.inboxPrefix = response.inboxPrefix;
+    this.#state.expiresMs = Date.parse(String(response.expires));
+    // Keep existing sentinel if not provided (e.g., from RenewBindingToken)
+    if (response.sentinel) {
+      this.#state.sentinel = response.sentinel;
+    }
+
+    // Only persist if we have sentinel credentials
+    if (this.#state.sentinel) {
+      persistAuth({
+        bindingToken: response.bindingToken,
+        inboxPrefix: response.inboxPrefix,
+        expires: new SvelteDate(String(response.expires)),
+        sentinel: this.#state.sentinel,
+      });
+    }
+  }
+
+  /**
+   * Clear persisted auth state without clearing session key or redirecting.
+   * Use this when auth fails and you need to force re-authentication.
+   */
+  clearAuth(): void {
+    clearPersistedAuth();
+    this.#state.bindingToken = null;
+    this.#state.inboxPrefix = null;
+    this.#state.expiresMs = null;
+    this.#state.sentinel = null;
+  }
+
+  /**
+   * Sign out by clearing all credentials and redirecting to login.
+   * This method does not return - it redirects the browser.
+   */
+  async signOut(remoteLogout?: () => Promise<unknown> | unknown): Promise<never> {
+    if (remoteLogout) {
+      try {
+        await remoteLogout();
+      } catch {
+        // Best-effort remote logout; local credential cleanup still proceeds.
+      }
+    }
+
+    await clearSessionKey();
+    this.clearAuth();
+    this.#state.handle = null;
+
+    const loginPath = this.#config.loginPath ?? "/login";
+    window.location.href = loginPath;
+    throw new Error("Signed out, redirecting to login");
+  }
+}
+
+/**
+ * Factory function to create an AuthState instance.
+ */
+export function createAuthState(config: AuthStateConfig): AuthState {
+  return new AuthState(config);
+}

package/src/state/nats.svelte.ts

@@ -0,0 +1,350 @@
+import {
+  jwtAuthenticator,
+  type NatsConnection,
+  wsconnect,
+} from "@nats-io/nats-core";
+import {
+  getPublicSessionKey,
+  natsConnectSigForBindingToken,
+  type SentinelCreds,
+  type SessionKeyHandle,
+  signBytes,
+} from "@qlever-llc/trellis-auth";
+import { AsyncResult, isErr, UnexpectedError } from "@qlever-llc/trellis-result";
+import {
+  API as AUTH_API,
+  type AuthRenewBindingTokenInput,
+  type AuthRenewBindingTokenOutput,
+} from "@qlever-llc/trellis-sdk-auth";
+import { createClient } from "@qlever-llc/trellis-trellis";
+import type { AuthState } from "./auth.svelte.ts";
+
+const AUTH_RENEW_API = {
+  rpc: {
+    "Auth.RenewBindingToken": AUTH_API.owned.rpc["Auth.RenewBindingToken"],
+  },
+  events: {},
+  subjects: {},
+} as const;
+
+type AuthRenewClient = {
+  request(
+    method: "Auth.RenewBindingToken",
+    input: AuthRenewBindingTokenInput,
+  ): Promise<{ take(): AuthRenewBindingTokenOutput | unknown }>;
+};
+
+export type Status = "disconnected" | "connecting" | "connected" | "error";
+
+export type NatsStateConfig = {
+  servers: string[];
+  onConnecting?: () => void;
+  onConnected?: () => void;
+  onDisconnect?: () => void;
+  onReconnecting?: () => void;
+  onReconnect?: () => void;
+  onError?: (error: Error) => void;
+  onAuthRequired?: () => void;
+};
+
+function requireBrowserAuth(authState: AuthState): {
+  handle: SessionKeyHandle;
+  bindingToken: string;
+  sentinel: SentinelCreds;
+} {
+  const handle = authState.handle;
+  const bindingToken = authState.bindingToken;
+  const sentinel = authState.sentinel;
+
+  if (!handle || !bindingToken || !sentinel) {
+    throw new Error("Not authenticated: missing binding token or sentinel");
+  }
+
+  return { handle, bindingToken, sentinel };
+}
+
+function createAuthRenewClient(
+  nc: NatsConnection,
+  handle: SessionKeyHandle,
+) : AuthRenewClient {
+  return createClient(
+    { API: { trellis: AUTH_RENEW_API } },
+    nc,
+    {
+      sessionKey: getPublicSessionKey(handle),
+      sign: (data: Uint8Array) => signBytes(handle, data),
+    },
+    { name: "auth-renew" },
+  ) as unknown as AuthRenewClient;
+}
+
+async function buildNatsAuthToken(
+  handle: SessionKeyHandle,
+  bindingToken: string,
+): Promise<string> {
+  const sessionKey = getPublicSessionKey(handle);
+  const sig = await natsConnectSigForBindingToken(handle, bindingToken);
+  return JSON.stringify({ v: 1, sessionKey, bindingToken, sig });
+}
+
+/**
+ * Svelte 5 runes-based reactive NATS connection state.
+ *
+ * Manages WebSocket connection to NATS server including:
+ * - Initial connection with authentication
+ * - Connection status monitoring
+ * - Automatic reconnection (within binding token TTL)
+ */
+export class NatsState {
+  nc: NatsConnection;
+  status: Status = $state("disconnected");
+
+  #servers: string[];
+  #authState: AuthState;
+  #config: NatsStateConfig;
+  #handle: SessionKeyHandle;
+  #tokenRef: { value: string };
+  #sentinel: SentinelCreds;
+  #trellis: AuthRenewClient;
+  #renewTimer: ReturnType<typeof setTimeout> | undefined;
+
+  private constructor(
+    nc: NatsConnection,
+    status: Status,
+    servers: string[],
+    authState: AuthState,
+    config: NatsStateConfig,
+    handle: SessionKeyHandle,
+    tokenRef: { value: string },
+    sentinel: SentinelCreds,
+  ) {
+    this.nc = nc;
+    this.status = status;
+    this.#servers = servers;
+    this.#authState = authState;
+    this.#config = config;
+    this.#handle = handle;
+    this.#tokenRef = tokenRef;
+    this.#sentinel = sentinel;
+    this.#trellis = createAuthRenewClient(nc, handle);
+    this.#monitorStatus();
+    this.#scheduleRenew();
+  }
+
+  /**
+   * Connect to NATS servers with authenticated credentials.
+   * Per ADR, browser clients use sentinel creds with jwtAuthenticator.
+   * The auth_token is passed via the token option for auth callout.
+   */
+  static async connect(
+    authState: AuthState,
+    config: NatsStateConfig,
+  ): Promise<NatsState> {
+    config.onConnecting?.();
+
+    await authState.init();
+    await authState.handleCallback();
+
+    if (!authState.isAuthenticated) {
+      config.onAuthRequired?.();
+      throw new Error("Not authenticated: missing binding token or sentinel");
+    }
+
+    const { handle, bindingToken, sentinel } = requireBrowserAuth(authState);
+    const inboxPrefix = authState.inboxPrefix ?? undefined;
+    const tokenRef = { value: await buildNatsAuthToken(handle, bindingToken) };
+
+    // Use jwtAuthenticator with sentinel credentials per ADR
+    const authenticator = jwtAuthenticator(
+      sentinel.jwt,
+      new TextEncoder().encode(sentinel.seed),
+    );
+
+    const nc = await wsconnect({
+      servers: config.servers,
+      authenticator,
+      token: tokenRef.value, // auth_token for auth callout
+      reconnect: true,
+      maxReconnectAttempts: 5,
+      reconnectTimeWait: 2000,
+      inboxPrefix,
+    });
+
+    config.onConnected?.();
+
+    const state = new NatsState(
+      nc,
+      "connected",
+      config.servers,
+      authState,
+      config,
+      handle,
+      tokenRef,
+      sentinel,
+    );
+
+    // Immediately renew binding token so localStorage has a valid (unconsumed) token.
+    // This prevents stale token issues on page reload.
+    await state.#renewBindingToken();
+
+    return state;
+  }
+
+  /**
+   * Reconnect to NATS with the existing binding token (if still valid).
+   * Uses stored sentinel credentials with jwtAuthenticator per ADR.
+   */
+  async reconnect(): Promise<void> {
+    if (this.status === "connecting") return;
+    this.status = "connecting";
+
+    await AsyncResult.try(() => this.nc.close());
+
+    const result = await AsyncResult.try(async () => {
+      await this.#authState.init();
+      if (!this.#authState.isAuthenticated) {
+        throw new UnexpectedError({
+          context: { message: "Not authenticated: binding token expired" },
+        });
+      }
+      const { handle, bindingToken } = requireBrowserAuth(this.#authState);
+      const inboxPrefix = this.#authState.inboxPrefix ?? undefined;
+      this.#tokenRef.value = await buildNatsAuthToken(handle, bindingToken);
+
+      const authenticator = jwtAuthenticator(
+        this.#sentinel.jwt,
+        new TextEncoder().encode(this.#sentinel.seed),
+      );
+
+      this.nc = await wsconnect({
+        servers: this.#servers,
+        authenticator,
+        token: this.#tokenRef.value,
+        reconnect: true,
+        maxReconnectAttempts: 5,
+        reconnectTimeWait: 2000,
+        inboxPrefix,
+      });
+
+      this.#trellis = createAuthRenewClient(this.nc, this.#handle);
+    });
+
+    if (result.isErr()) {
+      console.error("NATS reconnect failed:", result.error);
+      this.status = "error";
+      this.#config.onError?.(result.error);
+      return;
+    }
+
+    this.status = "connected";
+    this.#config.onReconnect?.();
+    this.#monitorStatus();
+
+    await this.#renewBindingToken();
+  }
+
+  #scheduleRenew(): void {
+    if (this.#renewTimer) clearTimeout(this.#renewTimer);
+
+    const expires = this.#authState.expires;
+    if (!expires) return;
+
+    const delayMs = Math.max(30_000, expires.getTime() - Date.now() - 60_000);
+    this.#renewTimer = setTimeout(() => {
+      void this.#renewBindingToken();
+    }, delayMs);
+  }
+
+  async #renewBindingToken(): Promise<void> {
+    const renew = async () => {
+      if (this.status !== "connected") return;
+      const res = await this.#trellis.request(
+        "Auth.RenewBindingToken",
+        {} satisfies AuthRenewBindingTokenInput,
+      );
+      const v = res.take();
+      if (isErr(v)) return;
+      const binding = v as AuthRenewBindingTokenOutput;
+      this.#authState.setBindingToken(binding);
+      this.#tokenRef.value = await buildNatsAuthToken(
+        this.#handle,
+        binding.bindingToken,
+      );
+    };
+
+    await AsyncResult.try(renew);
+    this.#scheduleRenew();
+  }
+
+  /**
+   * Disconnect from NATS.
+   */
+  async disconnect(): Promise<void> {
+    if (this.#renewTimer) clearTimeout(this.#renewTimer);
+    await AsyncResult.try(() => this.nc.close());
+    this.status = "disconnected";
+  }
+
+  async #monitorStatus(): Promise<void> {
+    for await (const s of this.nc.status()) {
+      switch (s.type) {
+        case "error": {
+          const data = "data" in s ? s.data : s.error;
+          const msg = data instanceof Error ? data.message : String(data);
+          const isAuthError =
+            msg.includes("authorization") || msg.includes("Authentication");
+          if (isAuthError) {
+            console.log(
+              "Auth error detected, attempting reconnect with fresh credentials",
+            );
+            void this.reconnect();
+          } else if (this.status !== "connected") {
+            this.status = "error";
+          }
+          break;
+        }
+
+        case "reconnect":
+          this.status = "connected";
+          this.#config.onReconnect?.();
+          break;
+
+        case "reconnecting":
+        case "forceReconnect":
+        case "staleConnection":
+          this.status = "connecting";
+          this.#config.onReconnecting?.();
+          break;
+
+        case "disconnect":
+        case "close":
+          this.status = "disconnected";
+          this.#config.onDisconnect?.();
+          void this.reconnect();
+          break;
+
+        case "ping":
+        case "update":
+        case "ldm":
+        case "slowConsumer":
+          // Informational events, no action needed
+          break;
+
+        default:
+          console.error("Unhandled NATS status event:", s);
+          this.status = "error";
+          break;
+      }
+    }
+  }
+}
+
+/**
+ * Factory function to create and connect a NatsState instance.
+ */
+export async function createNatsState(
+  authState: AuthState,
+  config: NatsStateConfig,
+): Promise<NatsState> {
+  return NatsState.connect(authState, config);
+}

package/src/state/trellis.svelte.ts

@@ -0,0 +1,78 @@
+import type { NatsConnection } from "@nats-io/nats-core";
+import { getPublicSessionKey, signBytes } from "@qlever-llc/trellis-auth";
+import { defineContract, type TrellisAPI } from "@qlever-llc/trellis-contracts";
+import { type ClientOpts, createClient, type Trellis, type TrellisAuth } from "@qlever-llc/trellis-trellis";
+import type { AuthState } from "./auth.svelte.ts";
+import type { NatsState } from "./nats.svelte.ts";
+
+export type TrellisClientContract<TApi extends TrellisAPI = TrellisAPI> = {
+  CONTRACT: Record<string, unknown>;
+  CONTRACT_DIGEST: string;
+  API: {
+    trellis: TApi;
+  };
+};
+
+export type TrellisStateConfig<TApi extends TrellisAPI = TrellisAPI> = {
+  serviceName: string;
+  contract?: TrellisClientContract<TApi>;
+};
+
+const DEFAULT_TRELLIS_CONTRACT = defineContract({
+  id: "trellis.svelte.browser@v1",
+  displayName: "Trellis Svelte Browser Client",
+  description: "Represent a browser client that only uses its locally declared Trellis APIs.",
+  kind: "browser",
+});
+
+/**
+ * Svelte 5 wrapper for Trellis client.
+ *
+ * Manages:
+ * - Trellis client instance
+ * - Session-key based request signing
+ */
+export class TrellisState {
+  readonly trellis: Trellis<TrellisAPI>;
+
+  private constructor(trellis: Trellis<TrellisAPI>) {
+    this.trellis = trellis;
+  }
+
+  /**
+   * Create a TrellisState instance with proper authentication.
+   */
+  static async create<TApi extends TrellisAPI = TrellisAPI>(
+    authState: AuthState,
+    natsState: NatsState,
+    config: TrellisStateConfig<TApi>,
+  ): Promise<TrellisState> {
+    const handle = await authState.init();
+    const contract = (config.contract ?? DEFAULT_TRELLIS_CONTRACT) as TrellisClientContract<TApi>;
+    const trellis = createClient(
+      contract,
+      natsState.nc,
+      {
+        sessionKey: getPublicSessionKey(handle),
+        sign: (data: Uint8Array) => signBytes(handle, data),
+      },
+      { name: config.serviceName },
+    ) as unknown as Trellis<TrellisAPI>;
+    return new TrellisState(trellis);
+  }
+
+  stop(): void {
+    // no-op (kept for convenience)
+  }
+}
+
+/**
+ * Factory function to create a TrellisState instance.
+ */
+export async function createTrellisState<TApi extends TrellisAPI = TrellisAPI>(
+  authState: AuthState,
+  natsState: NatsState,
+  config: TrellisStateConfig<TApi>,
+): Promise<TrellisState> {
+  return TrellisState.create(authState, natsState, config);
+}