@qlever-llc/trellis-svelte 0.4.0 → 0.6.0

package/README.md

@@ -4,4 +4,6 @@ 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`.
+Prefer `createTrellisApp(...)` for app-scoped auth creation and typed `app.getTrellis()` access without passing the contract around at every call site.
+
+Uses the contract/runtime model from `@qlever-llc/trellis/contracts` and `@qlever-llc/trellis`.

package/package.json

@@ -1,11 +1,19 @@
 {
   "name": "@qlever-llc/trellis-svelte",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "type": "module",
   "description": "Svelte components and state helpers for Trellis browser applications.",
   "license": "Apache-2.0",
+  "homepage": "https://github.com/Qlever-LLC/trellis#readme",
+  "bugs": {
+    "url": "https://github.com/Qlever-LLC/trellis/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Qlever-LLC/trellis"
+  },
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   },
   "files": [
     "src",
@@ -20,11 +28,7 @@
   },
   "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",
+    "@qlever-llc/trellis": "^0.6.0",
     "typebox": "^1.0.15"
   },
   "peerDependencies": {

package/src/components/TrellisProvider.svelte

@@ -1,32 +1,31 @@
 <script lang="ts">
   import type { NatsConnection } from "@nats-io/nats-core";
-  import { AsyncResult } from "@qlever-llc/trellis-result";
-  import type { Snippet } from "svelte";
+  import { AsyncResult } from "@qlever-llc/result";
   import { onDestroy } from "svelte";
+  import type { Snippet } from "svelte";
   import {
+    setAppContext,
     setAuthContext,
     setNatsStateContext,
     setTrellisContext,
   } from "../context.svelte.ts";
-  import { type AuthState, createAuthState } from "../state/auth.svelte.ts";
+  import type { AuthState, BindErrorResult } 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";
+  import { createTrellisState, type TrellisState } from "../state/trellis.svelte.ts";
+
+  type TrellisApp = {
+    auth: AuthState;
+  };
 
   type Props = {
     children: Snippet;
     loading?: Snippet;
-    authUrl: string;
-    natsServers: string[];
-    serviceName?: string;
-    contract?: TrellisClientContract;
-    loginPath?: string;
+    bindError?: Snippet<[BindErrorResult]>;
+    app: TrellisApp;
     onAuthExpired?: () => void;
     onAuthFailed?: (error: unknown) => void;
     onAuthRequired?: (redirectTo: string) => void;
+    onBindError?: (result: BindErrorResult) => void;
     onNatsConnecting?: () => void;
     onNatsConnected?: () => void;
     onNatsDisconnect?: () => void;
@@ -35,17 +34,15 @@
     onNatsError?: (error: Error) => void;
   };
 
-  const {
+  let {
     children,
     loading,
-    authUrl,
-    natsServers,
-    serviceName = "app",
-    contract,
-    loginPath = "/login",
+    bindError,
+    app,
     onAuthExpired,
     onAuthFailed,
     onAuthRequired,
+    onBindError,
     onNatsConnecting,
     onNatsConnected,
     onNatsDisconnect,
@@ -54,27 +51,14 @@
     onNatsError,
   }: Props = $props();
 
+  let bindErrorResult = $state<BindErrorResult | null>(null);
+
   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();
+  const isBrowser = typeof window !== "undefined";
 
   function getRedirectTo(): string {
     if (typeof window === "undefined") {
@@ -84,19 +68,42 @@
     return window.location.pathname + window.location.search;
   }
 
-  async function initialize(): Promise<InitContext> {
+  function redirectToLogin(redirectTo: string): void {
+    if (typeof window === "undefined") return;
+
+    const url = new URL(app.auth.loginPath, window.location.origin);
+    url.searchParams.set("redirectTo", redirectTo);
+    window.location.href = url.toString();
+  }
+
+  function handleAuthRequired(): void {
+    const redirectTo = getRedirectTo();
+    onAuthRequired?.(redirectTo);
+    if (!onAuthRequired) {
+      redirectToLogin(redirectTo);
+    }
+  }
+
+  async function initialize(): Promise<InitContext | null> {
     const result = await AsyncResult.try(async () => {
+      const authState = app.auth;
+
       await authState.init();
-      await authState.handleCallback();
+      const bindResult = await authState.handleCallback();
       authState.cleanupCallbackUrl();
 
+      if (bindResult !== null && bindResult.status !== "bound") {
+        bindErrorResult = bindResult;
+        onBindError?.(bindResult);
+        return null;
+      }
+
       if (!authState.isAuthenticated) {
-        onAuthRequired?.(getRedirectTo());
-        throw new AuthRequiredError();
+        handleAuthRequired();
+        return null;
       }
 
       const natsState = await createNatsState(authState, {
-        servers: natsServers,
         onConnecting: onNatsConnecting,
         onConnected: onNatsConnected,
         onDisconnect: onNatsDisconnect,
@@ -104,13 +111,13 @@
         onReconnect: onNatsReconnect,
         onError: onNatsError,
         onAuthRequired: () => {
-          onAuthRequired?.(getRedirectTo());
+          onAuthExpired?.();
+          handleAuthRequired();
         },
       });
 
       const trellisState = await createTrellisState(authState, natsState, {
-        serviceName,
-        contract,
+        contract: authState.contract,
       });
 
       return {
@@ -121,11 +128,9 @@
     });
 
     if (result.isErr()) {
-      authState.clearAuth();
       const error = result.error;
-      if (!(error instanceof AuthRequiredError)) {
-        onAuthFailed?.(error);
-      }
+      app.auth.clearAuth();
+      onAuthFailed?.(error);
       throw error;
     }
 
@@ -137,30 +142,54 @@
     });
   }
 
-  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,
-  });
+  const initPromise = isBrowser ? initialize() : null;
+  const readyPromise: Promise<InitContext> | null = initPromise?.then((ctx) => {
+    if (!ctx) {
+      throw new Error("Trellis context is not available");
+    }
+    return ctx;
+  }) ?? null;
+  const natsStatePromise: Promise<NatsState> | null = readyPromise?.then((ctx) => ctx.nats) ?? null;
+  const trellisPromise: Promise<TrellisState["trellis"]> | null = readyPromise?.then((ctx) => ctx.trellis.trellis) ?? null;
+  const natsPromise: Promise<NatsConnection> | null = readyPromise?.then((ctx) => ctx.nats.nc) ?? null;
+
+  if (readyPromise && natsStatePromise && trellisPromise && natsPromise) {
+    void readyPromise.catch(() => {});
+    setAppContext(() => app);
+    setAuthContext(() => app.auth);
+    setNatsStateContext(natsStatePromise);
+    setTrellisContext({
+      trellis: trellisPromise,
+      nats: natsPromise,
+    });
+  }
 
   onDestroy(() => {
-    void initPromise.then((ctx) => {
+    if (!readyPromise) return;
+
+    void readyPromise.then((ctx) => {
       ctx.trellis.stop();
       void ctx.nats.disconnect();
     });
   });
 </script>
 
-{#await initPromise}
+{#if !isBrowser}
   {#if loading}
     {@render loading()}
   {/if}
-{:then}
-  {@render children()}
-{/await}
+{:else}
+  {#await initPromise}
+    {#if loading}
+      {@render loading()}
+    {/if}
+  {:then ctx}
+    {#if bindErrorResult}
+      {#if bindError}
+        {@render bindError(bindErrorResult)}
+      {/if}
+    {:else if ctx}
+      {@render children()}
+    {/if}
+  {/await}
+{/if}

package/src/context.svelte.ts

@@ -1,47 +1,102 @@
-import { getContext, setContext } from "svelte";
-import type { TrellisAPI } from "@qlever-llc/trellis-contracts";
-import type { Trellis } from "@qlever-llc/trellis-trellis";
+import type { BaseError, Result } from "@qlever-llc/result";
 import type { NatsConnection } from "@nats-io/nats-core";
-import type { AuthState } from "./state/auth.svelte.ts";
+import type { InferSchemaType, Trellis, TrellisAPI } from "@qlever-llc/trellis";
+import { createContext } from "svelte";
+import { createAuthState, type AuthState, type AuthStateConfig, type SignInOptions } 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>;
+  trellis: Promise<Trellis<TrellisAPI>>;
   nats: Promise<NatsConnection>;
 };
 
-export function setTrellisContext<TA extends TrellisAPI>(
-  ctx: { trellis: Promise<Trellis<TA>>; nats: Promise<NatsConnection> },
+type TrellisContractLike<TA extends TrellisAPI = TrellisAPI> = {
+  API: {
+    trellis: TA;
+  };
+};
+
+type RequestOpts = {
+  timeout?: number;
+};
+
+type TypedTrellis<TA extends TrellisAPI> = Omit<Trellis<TrellisAPI>, "request" | "requestOrThrow"> & {
+  request<M extends keyof TA["rpc"] & string>(
+    method: M,
+    input: InferSchemaType<TA["rpc"][M]["input"]>,
+    opts?: RequestOpts,
+  ): Promise<Result<InferSchemaType<TA["rpc"][M]["output"]>, BaseError>>;
+  requestOrThrow<M extends keyof TA["rpc"] & string>(
+    method: M,
+    input: InferSchemaType<TA["rpc"][M]["input"]>,
+    opts?: RequestOpts,
+  ): Promise<InferSchemaType<TA["rpc"][M]["output"]>>;
+};
+
+function createTypedTrellis<TA extends TrellisAPI>(trellis: Trellis<TrellisAPI>): TypedTrellis<TA> {
+  return trellis as TypedTrellis<TA>;
+}
+
+export type BoundTrellisApp<TContract extends TrellisContractLike> = {
+  auth: AuthState;
+  signIn: (options?: SignInOptions) => Promise<never>;
+  getTrellis: () => Promise<TypedTrellis<TContract["API"]["trellis"]>>;
+};
+
+const [getTrellisContext, setTrellisContextValue] = createContext<TrellisContext>();
+const [getNatsStateContext, setNatsStateContextValue] = createContext<Promise<NatsState>>();
+const [getAuthContext, setAuthContextValue] = createContext<() => AuthState>();
+const [getAppContext, setAppContextValue] = createContext<() => unknown>();
+
+export function setTrellisContext(
+  ctx: TrellisContext,
 ): void {
-  setContext(TRELLIS_KEY, ctx.trellis as unknown as Promise<unknown>);
-  setContext(NATS_KEY, ctx.nats);
+  setTrellisContextValue(ctx);
 }
 
 export function setNatsStateContext(natsState: Promise<NatsState>): void {
-  setContext(NATS_STATE_KEY, natsState);
+  setNatsStateContextValue(natsState);
+}
+
+export function setAuthContext(getAuth: () => AuthState): void {
+  setAuthContextValue(getAuth);
 }
 
-export function setAuthContext(auth: AuthState): void {
-  setContext(AUTH_KEY, auth);
+export function setAppContext(getApp: () => unknown): void {
+  setAppContextValue(getApp);
 }
 
-export function getTrellis<TA extends TrellisAPI = TrellisAPI>(): Promise<Trellis<TA>> {
-  return getContext<Promise<unknown>>(TRELLIS_KEY) as Promise<Trellis<TA>>;
+export function createTrellisApp<TContract extends TrellisContractLike>(
+  config: AuthStateConfig & { contract: TContract },
+): BoundTrellisApp<TContract> {
+  const auth = createAuthState(config);
+
+  let app!: BoundTrellisApp<TContract>;
+  app = {
+    auth,
+    signIn: (options) => auth.signIn(options),
+    getTrellis: () => {
+      if (getAppContext()() !== app) {
+        throw new Error("getTrellis() was called outside the matching TrellisProvider");
+      }
+
+      return getTrellisContext().trellis.then((trellis) =>
+        createTypedTrellis<TContract["API"]["trellis"]>(trellis)
+      );
+    },
+  };
+
+  return app;
 }
 
 export function getNats(): Promise<NatsConnection> {
-  return getContext<Promise<NatsConnection>>(NATS_KEY);
+  return getTrellisContext().nats;
 }
 
 export function getNatsState(): Promise<NatsState> {
-  return getContext<Promise<NatsState>>(NATS_STATE_KEY);
+  return getNatsStateContext();
 }
 
 export function getAuth(): AuthState {
-  return getContext<AuthState>(AUTH_KEY);
+  return getAuthContext()();
 }

package/src/index.ts

@@ -1,6 +1,9 @@
 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";
+export { createTrellisApp, getAuth, getNats, getNatsState, setTrellisContext } from "./context.svelte.ts";
+export type { BoundTrellisApp } from "./context.svelte.ts";
+export { createPortalFlow, PortalFlowController, type CreatePortalFlowConfig } from "./portal_flow.svelte.ts";
+export { AuthState, type BindErrorResult, type BindResult, createAuthState, type SignInOptions } from "./state/auth.svelte.ts";
+export type { NatsStateConfig, Status as NatsStatus } from "./state/nats.svelte.ts";
+export { createNatsState, NatsState } from "./state/nats.svelte.ts";
+export type { TrellisClientContract, TrellisStateConfig } from "./state/trellis.svelte.ts";
+export { createTrellisState, TrellisState } from "./state/trellis.svelte.ts";

package/src/portal_flow.svelte.ts

@@ -0,0 +1,101 @@
+import {
+  fetchPortalFlowState,
+  portalFlowIdFromUrl,
+  portalProviderLoginUrl,
+  type PortalFlowState,
+  submitPortalApproval,
+  type AuthConfig,
+} from "@qlever-llc/trellis/auth";
+
+export type CreatePortalFlowConfig = AuthConfig & {
+  getUrl?: () => URL;
+};
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function defaultGetUrl(): URL {
+  return new URL(globalThis.location.href);
+}
+
+export class PortalFlowController {
+  flowId: string | null = $state(null);
+  state: PortalFlowState | null = $state(null);
+  loading = $state(false);
+  error: string | null = $state(null);
+
+  #config: AuthConfig;
+  #getUrl: () => URL;
+
+  constructor(config: CreatePortalFlowConfig) {
+    this.#config = { authUrl: config.authUrl };
+    this.#getUrl = config.getUrl ?? defaultGetUrl;
+  }
+
+  async load(): Promise<PortalFlowState | null> {
+    this.loading = true;
+    this.error = null;
+    this.state = null;
+
+    try {
+      const flowId = portalFlowIdFromUrl(this.#getUrl());
+      this.flowId = flowId;
+      if (!flowId) {
+        this.error = "Missing flow id.";
+        return null;
+      }
+
+      const state = await fetchPortalFlowState(this.#config, flowId);
+      this.state = state;
+      return state;
+    } catch (error) {
+      this.error = errorMessage(error);
+      this.state = null;
+      return null;
+    } finally {
+      this.loading = false;
+    }
+  }
+
+  providerUrl(providerId: string): string {
+    if (!this.flowId) {
+      throw new Error("Missing flow id.");
+    }
+
+    return portalProviderLoginUrl(this.#config, providerId, this.flowId);
+  }
+
+  async approve(): Promise<PortalFlowState | null> {
+    return this.#submit("approved");
+  }
+
+  async deny(): Promise<PortalFlowState | null> {
+    return this.#submit("denied");
+  }
+
+  async #submit(decision: "approved" | "denied"): Promise<PortalFlowState | null> {
+    if (!this.flowId) {
+      this.error = "Missing flow id.";
+      return null;
+    }
+
+    this.loading = true;
+    this.error = null;
+
+    try {
+      const state = await submitPortalApproval(this.#config, this.flowId, decision);
+      this.state = state;
+      return state;
+    } catch (error) {
+      this.error = errorMessage(error);
+      return null;
+    } finally {
+      this.loading = false;
+    }
+  }
+}
+
+export function createPortalFlow(config: CreatePortalFlowConfig): PortalFlowController {
+  return new PortalFlowController(config);
+}

package/src/state/auth.svelte.ts

@@ -1,21 +1,33 @@
 import {
   type BindResponse,
   type BindSuccessResponse,
+  bindFlow,
   bindSession,
-  buildLoginUrl,
   clearSessionKey,
-  extractAuthTokenFromFragment,
   getOrCreateSessionKey,
   getPublicSessionKey,
   type SentinelCreds,
   type SessionKeyHandle,
-} from "@qlever-llc/trellis-auth";
-import { Result } from "@qlever-llc/trellis-result";
+} from "@qlever-llc/trellis/auth";
+import { canonicalizeJsonValue } from "../../../auth/utils.ts";
+import { oauthInitSig } from "../../../auth/browser/session.ts";
+import { Result } from "@qlever-llc/result";
 import { SvelteDate } from "svelte/reactivity";
+import type { TrellisContractV1 } from "@qlever-llc/trellis";
 import { Type } from "typebox";
 import { Value } from "typebox/value";
+import type { TrellisClientContract } from "./trellis.svelte.ts";
+
+export type BindErrorResult =
+  | { status: "insufficient_capabilities"; missingCapabilities: string[] }
+  | { status: "approval_required" }
+  | { status: "approval_denied" }
+  | { status: "error"; message: string };
+
+export type BindResult = { status: "bound" } | BindErrorResult;
 
 const STORAGE_KEY = "trellis_auth";
+const AUTH_URL_STORAGE_KEY = "trellis_auth_url";
 
 type AuthStateData = {
   handle: SessionKeyHandle | null;
@@ -23,6 +35,7 @@ type AuthStateData = {
   inboxPrefix: string | null;
   expiresMs: number | null;
   sentinel: SentinelCreds | null;
+  natsServers: string[] | null;
 };
 
 type PersistedAuth = {
@@ -30,6 +43,7 @@ type PersistedAuth = {
   inboxPrefix: string;
   expires: string;
   sentinel: SentinelCreds;
+  natsServers: string[];
 };
 
 const PersistedAuthSchema = Type.Object({
@@ -40,6 +54,7 @@ const PersistedAuthSchema = Type.Object({
     jwt: Type.String(),
     seed: Type.String(),
   }, { additionalProperties: false }),
+  natsServers: Type.Array(Type.String()),
 }, { additionalProperties: false });
 
 function loadPersistedAuth(): PersistedAuth | null {
@@ -63,16 +78,18 @@ function persistAuth(state: {
   expires: Date;
   inboxPrefix: string;
   sentinel: SentinelCreds;
+  natsServers: string[];
 }): 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,
-    }),
+        bindingToken: state.bindingToken,
+        inboxPrefix: state.inboxPrefix,
+        expires: state.expires.toISOString(),
+        sentinel: state.sentinel,
+        natsServers: state.natsServers,
+      }),
   );
 }
 
@@ -82,11 +99,88 @@ function clearPersistedAuth(): void {
 }
 
 export type AuthStateConfig = {
-  authUrl: string; // https://auth.example.com
+  authUrl?: string; // https://auth.example.com
   loginPath?: string;
-  contract: { CONTRACT: Record<string, unknown> };
+  contract?: TrellisClientContract;
+};
+
+export type SignInOptions = {
+  authUrl?: string;
+  redirectTo?: string;
+  landingPath?: string;
+  context?: unknown;
 };
 
+function normalizeAuthUrl(authUrl: string): string {
+  return new URL(authUrl).toString().replace(/\/$/, "");
+}
+
+function encodeJsonForQuery(value: unknown): string {
+  const json = canonicalizeJsonValue(value);
+  const bytes = new TextEncoder().encode(json);
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+
+async function buildLoginUrl(options: {
+  authUrl: string;
+  redirectTo: string;
+  handle: SessionKeyHandle;
+  contract: Record<string, unknown>;
+  context?: unknown;
+}): Promise<string> {
+  const sessionKey = getPublicSessionKey(options.handle);
+  const sig = await oauthInitSig(options.handle, options.redirectTo, options.context);
+  const url = new URL(`${options.authUrl}/auth/login`);
+
+  url.searchParams.set("redirectTo", options.redirectTo);
+  url.searchParams.set("sessionKey", sessionKey);
+  url.searchParams.set("sig", sig);
+  url.searchParams.set("contract", encodeJsonForQuery(options.contract));
+  if (options.context !== undefined) {
+    url.searchParams.set("context", encodeJsonForQuery(options.context));
+  }
+
+  return url.href;
+}
+
+function loadPersistedAuthUrl(): string | null {
+  if (typeof localStorage === "undefined") return null;
+  const stored = localStorage.getItem(AUTH_URL_STORAGE_KEY);
+  if (!stored) return null;
+
+  return Result.try(() => normalizeAuthUrl(stored)).unwrapOr(null);
+}
+
+function persistAuthUrl(authUrl: string): string {
+  const normalized = normalizeAuthUrl(authUrl);
+  if (typeof localStorage !== "undefined") {
+    localStorage.setItem(AUTH_URL_STORAGE_KEY, normalized);
+  }
+  return normalized;
+}
+
+function resolveRedirectTo(
+  options: SignInOptions,
+  currentUrl: URL,
+): string {
+  if (options.redirectTo) {
+    return new URL(options.redirectTo, currentUrl.origin).toString();
+  }
+
+  const queryRedirect = currentUrl.searchParams.get("redirectTo");
+  if (queryRedirect) {
+    return new URL(queryRedirect, currentUrl.origin).toString();
+  }
+
+  if (options.landingPath) {
+    return new URL(options.landingPath, currentUrl.origin).toString();
+  }
+
+  return currentUrl.toString();
+}
+
 /**
  * Svelte 5 runes-based reactive authentication state.
  *
@@ -103,18 +197,55 @@ export class AuthState {
     inboxPrefix: null,
     expiresMs: null,
     sentinel: null,
+    natsServers: null,
   });
 
   #config: AuthStateConfig;
-  #bindingInProgress: Promise<BindResponse> | null = null;
+  #bindingInProgress: Promise<BindResult> | null = null;
 
   constructor(config: AuthStateConfig) {
-    this.#config = config;
+    this.#config = {
+      ...config,
+      authUrl: config.authUrl ? normalizeAuthUrl(config.authUrl) : undefined,
+    };
+  }
+
+  #getConfiguredAuthUrl(): string | null {
+    if (this.#config.authUrl) return this.#config.authUrl;
+
+    const persisted = loadPersistedAuthUrl();
+    if (!persisted) return null;
+
+    this.#config.authUrl = persisted;
+    return persisted;
+  }
+
+  #requireAuthUrl(): string {
+    const authUrl = this.#getConfiguredAuthUrl();
+    if (!authUrl) {
+      throw new Error("Auth URL is not configured");
+    }
+    return authUrl;
+  }
+
+  setAuthUrl(authUrl: string): string {
+    const normalized = persistAuthUrl(authUrl);
+    this.#config.authUrl = normalized;
+    return normalized;
   }
 
   get handle(): SessionKeyHandle | null {
     return this.#state.handle;
   }
+  get authUrl(): string | null {
+    return this.#getConfiguredAuthUrl();
+  }
+  get loginPath(): string {
+    return this.#config.loginPath ?? "/login";
+  }
+  get contract(): TrellisClientContract | undefined {
+    return this.#config.contract;
+  }
   get sessionKey(): string | null {
     return this.#state.handle ? getPublicSessionKey(this.#state.handle) : null;
   }
@@ -130,6 +261,9 @@ export class AuthState {
   get sentinel(): SentinelCreds | null {
     return this.#state.sentinel;
   }
+  get natsServers(): string[] | null {
+    return this.#state.natsServers;
+  }
   get isAuthenticated(): boolean {
     if (!this.#state.bindingToken) return false;
     if (this.#state.expiresMs === null) return false;
@@ -143,6 +277,8 @@ export class AuthState {
   async init(): Promise<SessionKeyHandle> {
     if (this.#state.handle) return this.#state.handle;
 
+    this.#getConfiguredAuthUrl();
+
     const handle = await getOrCreateSessionKey();
     this.#state.handle = handle;
 
@@ -152,6 +288,7 @@ export class AuthState {
       this.#state.inboxPrefix = persisted.inboxPrefix;
       this.#state.expiresMs = Date.parse(persisted.expires);
       this.#state.sentinel = persisted.sentinel;
+      this.#state.natsServers = persisted.natsServers;
     }
 
     return handle;
@@ -161,34 +298,28 @@ export class AuthState {
    * 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> {
+  async signIn(options: SignInOptions = {}): Promise<never> {
+    const authUrl = options.authUrl ? this.setAuthUrl(options.authUrl) : this.#requireAuthUrl();
     const handle = await this.init();
-    const url = await buildLoginUrl(
-      { authUrl: this.#config.authUrl },
-      provider,
-      redirectTo,
+    const currentUrl = new URL(window.location.href);
+    const url = await buildLoginUrl({
+      authUrl,
+      redirectTo: resolveRedirectTo(options, currentUrl),
       handle,
-      this.#config.contract.CONTRACT,
-    );
+      contract: this.#config.contract?.CONTRACT ?? {},
+      context: options.context,
+    });
     window.location.href = url;
-    throw new Error(`Redirecting to ${provider} for authentication`);
+    throw new Error("Redirecting to auth for provider selection");
   }
 
-  /**
-   * 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
+  async handleCallback(url: string = window.location.href): Promise<BindResult | null> {
     if (this.#bindingInProgress) return this.#bindingInProgress;
 
-    const authToken = extractAuthTokenFromFragment(url);
-    if (!authToken) return null;
+    const flowId = new URL(url).searchParams.get("flowId");
+    if (!flowId) return null;
 
-    this.#bindingInProgress = this.bind(authToken);
+    this.#bindingInProgress = this.#resolveCallback(flowId);
     try {
       return await this.#bindingInProgress;
     } finally {
@@ -196,13 +327,28 @@ export class AuthState {
     }
   }
 
+  async #resolveCallback(flowId: string): Promise<BindResult> {
+    try {
+      const response = await this.bindFlow(flowId);
+      return response.status === "bound"
+        ? { status: "bound" }
+        : { status: "insufficient_capabilities", missingCapabilities: response.missingCapabilities };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (message.includes("approval_denied")) return { status: "approval_denied" };
+      if (message.includes("approval_required")) return { status: "approval_required" };
+      return { status: "error", message };
+    }
+  }
+
   /**
-   * Clean up the callback URL by removing the authToken fragment.
+   * Clean up the callback URL by removing the auth flow query params.
    */
   cleanupCallbackUrl(url: string = window.location.href): void {
     const parsed = new URL(url);
-    if (parsed.hash) {
-      parsed.hash = "";
+    if (parsed.searchParams.has("flowId") || parsed.searchParams.has("authError")) {
+      parsed.searchParams.delete("flowId");
+      parsed.searchParams.delete("authError");
       window.history.replaceState({}, "", parsed.pathname + parsed.search);
     }
   }
@@ -218,7 +364,7 @@ export class AuthState {
   async #bind(authToken: string): Promise<BindResponse> {
     const handle = await this.init();
     const response = await bindSession(
-      { authUrl: this.#config.authUrl },
+      { authUrl: this.#requireAuthUrl() },
       handle,
       authToken,
     );
@@ -230,9 +376,25 @@ export class AuthState {
     return response;
   }
 
+  async bindFlow(flowId: string): Promise<BindResponse> {
+    const handle = await this.init();
+    const response = await bindFlow(
+      { authUrl: this.#requireAuthUrl() },
+      handle,
+      flowId,
+    );
+
+    if (response.status === "bound") {
+      this.setBindingToken(response);
+    }
+
+    return response;
+  }
+
   setBindingToken(
     response: Pick<BindSuccessResponse, "bindingToken" | "inboxPrefix" | "expires"> & {
       sentinel?: SentinelCreds;
+      natsServers?: string[];
     },
   ): void {
     this.#state.bindingToken = response.bindingToken;
@@ -242,14 +404,18 @@ export class AuthState {
     if (response.sentinel) {
       this.#state.sentinel = response.sentinel;
     }
+    if (response.natsServers) {
+      this.#state.natsServers = response.natsServers;
+    }
 
     // Only persist if we have sentinel credentials
-    if (this.#state.sentinel) {
+    if (this.#state.sentinel && this.#state.natsServers) {
       persistAuth({
         bindingToken: response.bindingToken,
         inboxPrefix: response.inboxPrefix,
         expires: new SvelteDate(String(response.expires)),
         sentinel: this.#state.sentinel,
+        natsServers: this.#state.natsServers,
       });
     }
   }
@@ -264,6 +430,7 @@ export class AuthState {
     this.#state.inboxPrefix = null;
     this.#state.expiresMs = null;
     this.#state.sentinel = null;
+    this.#state.natsServers = null;
   }
 
   /**
@@ -283,8 +450,7 @@ export class AuthState {
     this.clearAuth();
     this.#state.handle = null;
 
-    const loginPath = this.#config.loginPath ?? "/login";
-    window.location.href = loginPath;
+    window.location.href = this.loginPath;
     throw new Error("Signed out, redirecting to login");
   }
 }

package/src/state/nats.svelte.ts

@@ -3,20 +3,20 @@ import {
   type NatsConnection,
   wsconnect,
 } from "@nats-io/nats-core";
+import { createClient, type Trellis } from "@qlever-llc/trellis";
 import {
   getPublicSessionKey,
   natsConnectSigForBindingToken,
   type SentinelCreds,
   type SessionKeyHandle,
   signBytes,
-} from "@qlever-llc/trellis-auth";
-import { AsyncResult, isErr, UnexpectedError } from "@qlever-llc/trellis-result";
+} from "@qlever-llc/trellis/auth";
+import { AsyncResult, UnexpectedError } from "@qlever-llc/result";
 import {
   API as AUTH_API,
   type AuthRenewBindingTokenInput,
   type AuthRenewBindingTokenOutput,
-} from "@qlever-llc/trellis-sdk-auth";
-import { createClient } from "@qlever-llc/trellis-trellis";
+} from "@qlever-llc/trellis/sdk/auth";
 import type { AuthState } from "./auth.svelte.ts";
 
 const AUTH_RENEW_API = {
@@ -25,19 +25,34 @@ const AUTH_RENEW_API = {
   },
   events: {},
   subjects: {},
+  operations: {},
 } as const;
 
-type AuthRenewClient = {
-  request(
-    method: "Auth.RenewBindingToken",
-    input: AuthRenewBindingTokenInput,
-  ): Promise<{ take(): AuthRenewBindingTokenOutput | unknown }>;
+const AUTH_RENEW_CONTRACT = {
+  API: {
+    trellis: AUTH_RENEW_API,
+  },
+} as const;
+
+function createAuthRenewClient(
+  nc: NatsConnection,
+  handle: SessionKeyHandle,
+): Trellis<typeof AUTH_RENEW_API> {
+  return createClient<typeof AUTH_RENEW_API>(
+    AUTH_RENEW_CONTRACT,
+    nc,
+    {
+      sessionKey: getPublicSessionKey(handle),
+      sign: (data: Uint8Array) => signBytes(handle, data),
+    },
+    { name: "auth-renew" },
+  );
 };
 
 export type Status = "disconnected" | "connecting" | "connected" | "error";
 
 export type NatsStateConfig = {
-  servers: string[];
+  servers?: string[];
   onConnecting?: () => void;
   onConnected?: () => void;
   onDisconnect?: () => void;
@@ -63,19 +78,15 @@ function requireBrowserAuth(authState: AuthState): {
   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;
+function resolveServers(
+  authState: AuthState,
+  config: NatsStateConfig,
+): string[] {
+  const servers = config.servers ?? authState.natsServers;
+  if (!servers || servers.length === 0) {
+    throw new Error("Not authenticated: missing natsServers from auth state");
+  }
+  return servers;
 }
 
 async function buildNatsAuthToken(
@@ -105,7 +116,7 @@ export class NatsState {
   #handle: SessionKeyHandle;
   #tokenRef: { value: string };
   #sentinel: SentinelCreds;
-  #trellis: AuthRenewClient;
+  #trellis: ReturnType<typeof createAuthRenewClient>;
   #renewTimer: ReturnType<typeof setTimeout> | undefined;
 
   private constructor(
@@ -151,6 +162,7 @@ export class NatsState {
     }
 
     const { handle, bindingToken, sentinel } = requireBrowserAuth(authState);
+    const servers = resolveServers(authState, config);
     const inboxPrefix = authState.inboxPrefix ?? undefined;
     const tokenRef = { value: await buildNatsAuthToken(handle, bindingToken) };
 
@@ -161,7 +173,7 @@ export class NatsState {
     );
 
     const nc = await wsconnect({
-      servers: config.servers,
+      servers,
       authenticator,
       token: tokenRef.value, // auth_token for auth callout
       reconnect: true,
@@ -175,7 +187,7 @@ export class NatsState {
     const state = new NatsState(
       nc,
       "connected",
-      config.servers,
+      servers,
       authState,
       config,
       handle,
@@ -258,13 +270,14 @@ export class NatsState {
   async #renewBindingToken(): Promise<void> {
     const renew = async () => {
       if (this.status !== "connected") return;
-      const res = await this.#trellis.request(
+      const requestOrThrow = this.#trellis.requestOrThrow.bind(this.#trellis) as (
+        method: string,
+        input: unknown,
+      ) => Promise<unknown>;
+      const binding = await requestOrThrow(
         "Auth.RenewBindingToken",
         {} satisfies AuthRenewBindingTokenInput,
-      );
-      const v = res.take();
-      if (isErr(v)) return;
-      const binding = v as AuthRenewBindingTokenOutput;
+      ) as AuthRenewBindingTokenOutput;
       this.#authState.setBindingToken(binding);
       this.#tokenRef.value = await buildNatsAuthToken(
         this.#handle,

package/src/state/trellis.svelte.ts

@@ -1,12 +1,16 @@
-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 {
+  createClient,
+  defineContract,
+  type Trellis,
+  type TrellisAPI,
+  type TrellisContractV1,
+} from "@qlever-llc/trellis";
+import { getPublicSessionKey, signBytes } from "@qlever-llc/trellis/auth";
 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: TrellisContractV1;
   CONTRACT_DIGEST: string;
   API: {
     trellis: TApi;
@@ -14,7 +18,6 @@ export type TrellisClientContract<TApi extends TrellisAPI = TrellisAPI> = {
 };
 
 export type TrellisStateConfig<TApi extends TrellisAPI = TrellisAPI> = {
-  serviceName: string;
   contract?: TrellisClientContract<TApi>;
 };
 
@@ -23,7 +26,7 @@ const DEFAULT_TRELLIS_CONTRACT = defineContract({
   displayName: "Trellis Svelte Browser Client",
   description: "Represent a browser client that only uses its locally declared Trellis APIs.",
   kind: "browser",
-});
+}) satisfies TrellisClientContract<TrellisAPI>;
 
 /**
  * Svelte 5 wrapper for Trellis client.
@@ -32,33 +35,36 @@ const DEFAULT_TRELLIS_CONTRACT = defineContract({
  * - Trellis client instance
  * - Session-key based request signing
  */
-export class TrellisState {
-  readonly trellis: Trellis<TrellisAPI>;
+export class TrellisState<TApi extends TrellisAPI = TrellisAPI> {
+  readonly trellis: Trellis<TApi>;
 
-  private constructor(trellis: Trellis<TrellisAPI>) {
+  private constructor(trellis: Trellis<TApi>) {
     this.trellis = trellis;
   }
 
   /**
    * Create a TrellisState instance with proper authentication.
    */
-  static async create<TApi extends TrellisAPI = TrellisAPI>(
+  static async create<TApi extends TrellisAPI>(
     authState: AuthState,
     natsState: NatsState,
     config: TrellisStateConfig<TApi>,
-  ): Promise<TrellisState> {
+  ): Promise<TrellisState<TApi>> {
     const handle = await authState.init();
     const contract = (config.contract ?? DEFAULT_TRELLIS_CONTRACT) as TrellisClientContract<TApi>;
-    const trellis = createClient(
+    const clientName = typeof contract.CONTRACT.id === "string" && contract.CONTRACT.id.length > 0
+      ? contract.CONTRACT.id
+      : "client";
+    const trellis = createClient<TApi>(
       contract,
       natsState.nc,
       {
         sessionKey: getPublicSessionKey(handle),
         sign: (data: Uint8Array) => signBytes(handle, data),
       },
-      { name: config.serviceName },
-    ) as unknown as Trellis<TrellisAPI>;
-    return new TrellisState(trellis);
+      { name: clientName },
+    );
+    return new TrellisState<TApi>(trellis);
   }
 
   stop(): void {
@@ -69,10 +75,10 @@ export class TrellisState {
 /**
  * Factory function to create a TrellisState instance.
  */
-export async function createTrellisState<TApi extends TrellisAPI = TrellisAPI>(
+export async function createTrellisState<TApi extends TrellisAPI>(
   authState: AuthState,
   natsState: NatsState,
   config: TrellisStateConfig<TApi>,
-): Promise<TrellisState> {
-  return TrellisState.create(authState, natsState, config);
+): Promise<TrellisState<TApi>> {
+  return TrellisState.create<TApi>(authState, natsState, config);
 }