@structured-id/ui-core 0.1.5

package/src/components/SidStatusBadge.vue

@@ -0,0 +1,71 @@
+<script setup lang="ts">
+/**
+ * Status badge component with semantic colors.
+ *
+ * Framework-agnostic (pure Vue 3, no Quasar dependency).
+ * Consuming apps can override styles via CSS custom properties.
+ */
+
+export type BadgeVariant =
+  | "active"
+  | "inactive"
+  | "pending"
+  | "error"
+  | "warning";
+
+const props = withDefaults(
+  defineProps<{
+    label: string;
+    variant?: BadgeVariant;
+  }>(),
+  {
+    variant: "active",
+  },
+);
+
+const variantClasses: Record<BadgeVariant, string> = {
+  active: "sid-badge--active",
+  inactive: "sid-badge--inactive",
+  pending: "sid-badge--pending",
+  error: "sid-badge--error",
+  warning: "sid-badge--warning",
+};
+</script>
+
+<template>
+  <span class="sid-badge" :class="variantClasses[props.variant]">
+    {{ props.label }}
+  </span>
+</template>
+
+<style scoped>
+.sid-badge {
+  display: inline-flex;
+  align-items: center;
+  padding: 2px 8px;
+  border-radius: 12px;
+  font-size: 0.75rem;
+  font-weight: 500;
+  line-height: 1.5;
+}
+.sid-badge--active {
+  background: var(--sid-badge-active-bg, #e8f5e9);
+  color: var(--sid-badge-active-color, #2e7d32);
+}
+.sid-badge--inactive {
+  background: var(--sid-badge-inactive-bg, #f5f5f5);
+  color: var(--sid-badge-inactive-color, #757575);
+}
+.sid-badge--pending {
+  background: var(--sid-badge-pending-bg, #fff3e0);
+  color: var(--sid-badge-pending-color, #e65100);
+}
+.sid-badge--error {
+  background: var(--sid-badge-error-bg, #ffebee);
+  color: var(--sid-badge-error-color, #c62828);
+}
+.sid-badge--warning {
+  background: var(--sid-badge-warning-bg, #fff8e1);
+  color: var(--sid-badge-warning-color, #f57f17);
+}
+</style>

package/src/components/index.ts

@@ -0,0 +1,5 @@
+export { default as SidAvatar } from "./SidAvatar.vue";
+export type { AvatarSize } from "./SidAvatar.vue";
+export { default as SidStatusBadge } from "./SidStatusBadge.vue";
+export type { BadgeVariant } from "./SidStatusBadge.vue";
+export { default as SidConfirmDialog } from "./SidConfirmDialog.vue";

package/src/composables/index.ts

@@ -0,0 +1,10 @@
+export { useAuth } from "./useAuth";
+export {
+  useGrpc,
+  initGrpc,
+  getTransport,
+  closeTransport,
+  getTransportType,
+  type TransportType,
+} from "./useGrpc";
+export { useSession, type SessionCallbacks } from "./useSession";

package/src/composables/useAuth.ts

@@ -0,0 +1,40 @@
+import { computed } from "vue";
+import { useAuthStore } from "../stores/auth";
+
+/**
+ * Vue composable for authentication state and actions.
+ *
+ * Wraps the Pinia auth store with reactive computed properties.
+ * Post BFF migration (#536i-3): no token accessors — session validity
+ * is based on httpOnly cookie checked via BFF /auth/userinfo on boot.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useAuth } from '@structured-id/ui-core'
+ * const { isAuthenticated, displayName, logout } = useAuth()
+ * </script>
+ * ```
+ */
+export function useAuth() {
+  const store = useAuthStore();
+
+  const isAuthenticated = computed(() => store.isAuthenticated);
+  const displayName = computed(() => store.displayName);
+  const email = computed(() => store.email);
+  const profileId = computed(() => store.profileId);
+  const preferredUsername = computed(() => store.preferredUsername);
+  const sessionId = computed(() => store.sessionId);
+
+  return {
+    isAuthenticated,
+    displayName,
+    email,
+    profileId,
+    preferredUsername,
+    sessionId,
+    setBffSession: store.setBffSession,
+    setProfile: store.setProfile,
+    logout: store.logout,
+  };
+}

package/src/composables/useBffAuth.ts

@@ -0,0 +1,147 @@
+/**
+ * BFF (Backend-For-Frontend) session management composable.
+ *
+ * After migration from localStorage to cookie-based auth (#536i-3):
+ *   - Tokens are stored server-side in sid-auth-proxy BFF sessions
+ *   - SPA only holds a non-httpOnly CSRF cookie + httpOnly session cookie
+ *   - gRPC calls go through BFF proxy which injects Bearer header
+ *   - Client JS never sees the access token
+ *
+ * Usage:
+ *   1. Call `initBff(bffBaseUrl)` at app boot (e.g., VITE_BFF_URL)
+ *   2. Call `checkBffSession()` to verify session + populate auth store
+ *   3. Call `startBffLogin()` to redirect user to PKCE auth flow
+ *   4. Call `bffLogout()` to clear session (sends X-CSRF-Token header)
+ */
+
+/** User info returned from BFF /auth/userinfo endpoint. */
+export interface BffUserInfo {
+  /** Subject identifier (ProfileId for CE, PersonaId for SaaS). */
+  sub: string;
+  /** Email address (if available in session claims). */
+  email?: string | null;
+  /** Display name (full name from profile). */
+  name?: string | null;
+  /** Username or email — preferred identifier for display. */
+  preferred_username?: string | null;
+  /** Group memberships. */
+  groups?: string[] | null;
+  /** Authentication Context Class Reference (acr_values). */
+  acr?: string | null;
+  /** Role assignments. */
+  roles?: string[] | null;
+}
+
+let _bffBaseUrl: string | null = null;
+let _bffCookieName: string = "__Host-sid-bff";
+
+/**
+ * Initialize BFF configuration. Call once at app boot.
+ *
+ * @param baseUrl  BFF base URL (e.g., "https://app.structured.id" or VITE_BFF_URL)
+ * @param cookieName  BFF session cookie name (default: "__Host-sid-bff")
+ */
+export function initBff(baseUrl: string, cookieName?: string): void {
+  _bffBaseUrl = baseUrl;
+  if (cookieName) _bffCookieName = cookieName;
+}
+
+/** Get the configured BFF base URL, or null if not initialized. */
+export function getBffBaseUrl(): string | null {
+  return _bffBaseUrl;
+}
+
+/**
+ * Read the CSRF token from the non-httpOnly CSRF cookie.
+ * The BFF sets a cookie `{cookieName}_csrf=<token>; SameSite=Lax` (NOT httpOnly)
+ * so JS can read it for double-submit CSRF protection.
+ */
+function readCsrfToken(): string | null {
+  const name = `${_bffCookieName}_csrf=`;
+  const cookies = document.cookie.split("; ");
+  const found = cookies.find((c) => c.startsWith(name));
+  return found ? (found.split("=")[1] ?? null) : null;
+}
+
+/**
+ * Check if the BFF session is valid by calling GET /auth/userinfo.
+ *
+ * Returns user info if session is active, null if unauthenticated.
+ * The browser automatically sends the httpOnly session cookie.
+ */
+export async function checkBffSession(
+  bffBaseUrl?: string,
+): Promise<BffUserInfo | null> {
+  const base = bffBaseUrl ?? _bffBaseUrl;
+  if (!base) return null;
+  try {
+    const resp = await fetch(`${base}/auth/userinfo`, {
+      credentials: "include",
+    });
+    if (resp.status === 401 || resp.status === 404) return null;
+    if (!resp.ok) return null;
+    return (await resp.json()) as BffUserInfo;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Redirect user to BFF login (PKCE flow initiation).
+ *
+ * After successful login, BFF sets httpOnly session cookie and redirects
+ * back to the SPA. The SPA should call checkBffSession() on load to restore state.
+ *
+ * @param bffBaseUrl  Override BFF base URL (uses configured URL if not provided)
+ * @param postLoginRedirect  URL to redirect to after successful auth
+ */
+export function startBffLogin(
+  bffBaseUrl?: string,
+  postLoginRedirect?: string,
+): void {
+  const base = bffBaseUrl ?? _bffBaseUrl;
+  if (!base) {
+    console.warn("[BFF] Not initialized. Call initBff() at app boot.");
+    return;
+  }
+  const url = postLoginRedirect
+    ? `${base}/auth/login?post_login_redirect=${encodeURIComponent(postLoginRedirect)}`
+    : `${base}/auth/login`;
+  window.location.href = url;
+}
+
+/**
+ * Log out by calling POST /auth/logout with X-CSRF-Token header.
+ *
+ * The BFF validates the CSRF header, clears server-side session,
+ * and sends Set-Cookie headers to clear both cookies.
+ *
+ * @param bffBaseUrl  Override BFF base URL
+ */
+export async function bffLogout(bffBaseUrl?: string): Promise<void> {
+  const base = bffBaseUrl ?? _bffBaseUrl;
+  if (!base) return;
+  const csrf = readCsrfToken();
+  try {
+    await fetch(`${base}/auth/logout`, {
+      method: "POST",
+      credentials: "include",
+      headers: csrf ? { "X-CSRF-Token": csrf } : {},
+    });
+  } catch {
+    // Best-effort — local state is cleared by caller regardless
+  }
+}
+
+/**
+ * Vue composable for BFF auth actions.
+ */
+export function useBffAuth() {
+  return {
+    checkBffSession,
+    startBffLogin,
+    bffLogout,
+    getBffBaseUrl,
+    initBff,
+  };
+}

package/src/composables/useGrpc.test.ts

@@ -0,0 +1,196 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// ---------------------------------------------------------------------------
+// Mock modules BEFORE importing the module under test
+// ---------------------------------------------------------------------------
+
+const mockAdaptiveInit = vi
+  .fn<[], Promise<void>>()
+  .mockResolvedValue(undefined);
+const mockAdaptiveClose = vi.fn();
+const mockAdaptiveActiveTransport = vi
+  .fn<[], string>()
+  .mockReturnValue("grpc-web");
+
+vi.mock("../transport/adaptive", () => ({
+  AdaptiveRpcTransport: vi.fn().mockImplementation(() => ({
+    init: mockAdaptiveInit,
+    close: mockAdaptiveClose,
+    get activeTransport() {
+      return mockAdaptiveActiveTransport();
+    },
+  })),
+}));
+
+vi.mock("@protobuf-ts/grpcweb-transport", () => ({
+  GrpcWebFetchTransport: vi
+    .fn()
+    .mockImplementation(() => ({ type: "grpc-web-transport" })),
+}));
+
+// Import AFTER mocks
+import { GrpcWebFetchTransport } from "@protobuf-ts/grpcweb-transport";
+import { AdaptiveRpcTransport } from "../transport/adaptive";
+import {
+  initGrpc,
+  getTransport,
+  closeTransport,
+  getTransportType,
+  useGrpc,
+} from "./useGrpc";
+import type { GrpcConfig } from "../types/auth";
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("useGrpc", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    // Reset transport state by calling close between tests
+    closeTransport();
+  });
+
+  describe("initGrpc — without WebTransport URL", () => {
+    it("creates GrpcWebFetchTransport with baseUrl and credentials", () => {
+      const config: GrpcConfig = { baseUrl: "https://api.sid.example.com" };
+      initGrpc(config);
+
+      expect(GrpcWebFetchTransport).toHaveBeenCalledWith({
+        baseUrl: "https://api.sid.example.com",
+        fetchInit: { credentials: "include" },
+      });
+      expect(AdaptiveRpcTransport).not.toHaveBeenCalled();
+    });
+
+    it("getTransportType returns grpc-web", () => {
+      initGrpc({ baseUrl: "https://api.sid.example.com" });
+      expect(getTransportType()).toBe("grpc-web");
+    });
+  });
+
+  describe("initGrpc — with WebTransport URL", () => {
+    it("creates AdaptiveRpcTransport with fetchInit credentials", () => {
+      const config: GrpcConfig = {
+        baseUrl: "https://api.sid.example.com",
+        webTransportUrl: "https://wt.api.sid.example.com",
+      };
+      initGrpc(config);
+
+      expect(AdaptiveRpcTransport).toHaveBeenCalledWith(
+        expect.objectContaining({
+          grpcWebUrl: "https://api.sid.example.com",
+          webTransportUrl: "https://wt.api.sid.example.com",
+          fetchInit: { credentials: "include" },
+        }),
+      );
+      expect(GrpcWebFetchTransport).not.toHaveBeenCalled();
+    });
+
+    it("calls adaptive.init() non-blocking on creation", async () => {
+      initGrpc({
+        baseUrl: "https://api.sid.example.com",
+        webTransportUrl: "https://wt.api.sid.example.com",
+      });
+
+      // init() should be called (non-blocking fire-and-forget)
+      // Give microtasks time to run
+      await Promise.resolve();
+      expect(mockAdaptiveInit).toHaveBeenCalled();
+    });
+
+    it("passes all WebTransport options to AdaptiveRpcTransport", () => {
+      const onChange = vi.fn();
+      initGrpc({
+        baseUrl: "https://api.sid.example.com",
+        webTransportUrl: "https://wt.api.sid.example.com",
+        webTransportCertHash: "abcdef1234567890",
+        webTransportReconnectDelay: 3000,
+        onTransportChange: onChange,
+      });
+
+      expect(AdaptiveRpcTransport).toHaveBeenCalledWith(
+        expect.objectContaining({
+          grpcWebUrl: "https://api.sid.example.com",
+          webTransportUrl: "https://wt.api.sid.example.com",
+          webTransportCertHash: "abcdef1234567890",
+          reconnectDelay: 3000,
+          onTransportChange: onChange,
+          fetchInit: { credentials: "include" },
+        }),
+      );
+    });
+
+    it("getTransportType delegates to AdaptiveRpcTransport.activeTransport", () => {
+      mockAdaptiveActiveTransport.mockReturnValue("webtransport");
+      initGrpc({
+        baseUrl: "https://api.sid.example.com",
+        webTransportUrl: "https://wt.api.sid.example.com",
+      });
+
+      expect(getTransportType()).toBe("webtransport");
+    });
+  });
+
+  describe("getTransport", () => {
+    it("throws before initGrpc is called", () => {
+      expect(() => getTransport()).toThrow("gRPC transport not initialized");
+    });
+
+    it("returns transport after initGrpc", () => {
+      initGrpc({ baseUrl: "https://api.sid.example.com" });
+      expect(() => getTransport()).not.toThrow();
+      expect(getTransport()).toBeDefined();
+    });
+  });
+
+  describe("useGrpc composable", () => {
+    it("transport.value is null before initGrpc", () => {
+      const { transport } = useGrpc();
+      expect(transport.value).toBeNull();
+    });
+
+    it("transport.value is set when initGrpc was called before useGrpc", () => {
+      initGrpc({ baseUrl: "https://api.sid.example.com" });
+      const { transport } = useGrpc();
+      expect(transport.value).not.toBeNull();
+    });
+
+    it("returns getTransport and initGrpc functions", () => {
+      const composable = useGrpc();
+      expect(typeof composable.getTransport).toBe("function");
+      expect(typeof composable.initGrpc).toBe("function");
+    });
+
+    it("transport.value is null after closeTransport", () => {
+      initGrpc({ baseUrl: "https://api.sid.example.com" });
+      closeTransport();
+      const { transport } = useGrpc();
+      expect(transport.value).toBeNull();
+    });
+  });
+
+  describe("closeTransport", () => {
+    it("calls close() on AdaptiveRpcTransport", () => {
+      initGrpc({
+        baseUrl: "https://api.sid.example.com",
+        webTransportUrl: "https://wt.api.sid.example.com",
+      });
+
+      closeTransport();
+      expect(mockAdaptiveClose).toHaveBeenCalled();
+    });
+
+    it("resets transport to null (getTransport throws after close)", () => {
+      initGrpc({ baseUrl: "https://api.sid.example.com" });
+      closeTransport();
+      expect(() => getTransport()).toThrow("gRPC transport not initialized");
+    });
+
+    it("does not call close() on plain GrpcWebFetchTransport (no close method)", () => {
+      initGrpc({ baseUrl: "https://api.sid.example.com" });
+      // Should not throw even though GrpcWebFetchTransport has no close()
+      expect(() => closeTransport()).not.toThrow();
+    });
+  });
+});

package/src/composables/useGrpc.ts

@@ -0,0 +1,120 @@
+import { GrpcWebFetchTransport } from "@protobuf-ts/grpcweb-transport";
+import type { RpcTransport } from "@protobuf-ts/runtime-rpc";
+import { ref, type Ref } from "vue";
+import type { GrpcConfig } from "../types/auth";
+import { AdaptiveRpcTransport } from "../transport/adaptive";
+import type { TransportType } from "../transport/adaptive";
+
+/** Shared RPC transport instance (gRPC-web or AdaptiveRpcTransport). */
+let _transport: RpcTransport | null = null;
+/** Separate reference to AdaptiveRpcTransport when active (avoids instanceof). */
+let _adaptive: AdaptiveRpcTransport | null = null;
+
+/**
+ * Initialize the gRPC transport. Call once at app startup.
+ *
+ * When `config.webTransportUrl` is provided, creates an AdaptiveRpcTransport
+ * with WebTransport as the primary and gRPC-web as the fallback. The initial
+ * WebTransport connection is attempted asynchronously (non-blocking).
+ *
+ * Without `config.webTransportUrl`, falls back to plain gRPC-web (same as before).
+ *
+ * After BFF migration (#536i-3): `credentials: "include"` is always set
+ * so the httpOnly BFF session cookie is sent with every gRPC-web request.
+ *
+ * @example
+ * ```ts
+ * // gRPC-web only
+ * initGrpc({ baseUrl: 'https://api.example.com' })
+ *
+ * // With WebTransport failover
+ * initGrpc({
+ *   baseUrl: 'https://api.example.com',
+ *   webTransportUrl: 'https://wt.api.example.com',
+ * })
+ * ```
+ */
+export function initGrpc(config: GrpcConfig): void {
+  if (config.webTransportUrl) {
+    const adaptive = new AdaptiveRpcTransport({
+      grpcWebUrl: config.baseUrl,
+      webTransportUrl: config.webTransportUrl,
+      webTransportCertHash: config.webTransportCertHash,
+      reconnectDelay: config.webTransportReconnectDelay,
+      onTransportChange: config.onTransportChange,
+      // Always include credentials so the BFF session cookie is attached.
+      // The BFF proxy exchanges the cookie for a Bearer token server-side.
+      fetchInit: { credentials: "include" },
+    });
+    // Attempt WebTransport connection in background — non-blocking.
+    adaptive.init().catch(() => {
+      // Silently falls back to gRPC-web if WebTransport is unavailable.
+    });
+    _adaptive = adaptive;
+    _transport = adaptive;
+  } else {
+    _adaptive = null;
+    _transport = new GrpcWebFetchTransport({
+      baseUrl: config.baseUrl,
+      // Always include credentials so the BFF session cookie is attached.
+      // The BFF proxy exchanges the cookie for a Bearer token server-side.
+      fetchInit: { credentials: "include" },
+    });
+  }
+}
+
+/**
+ * Get the shared RPC transport. Throws if not initialized.
+ */
+export function getTransport(): RpcTransport {
+  if (!_transport) {
+    throw new Error(
+      "gRPC transport not initialized. Call initGrpc() at app startup.",
+    );
+  }
+  return _transport;
+}
+
+/**
+ * Close the transport and release resources (timers, connections).
+ * Call during app teardown if using WebTransport.
+ */
+export function closeTransport(): void {
+  _adaptive?.close();
+  _adaptive = null;
+  _transport = null;
+}
+
+/**
+ * Get the currently active transport type.
+ * Returns "grpc-web" if AdaptiveRpcTransport is not used or WebTransport
+ * is not available.
+ */
+export function getTransportType(): TransportType {
+  return _adaptive?.activeTransport ?? "grpc-web";
+}
+
+/**
+ * Vue composable for gRPC transport.
+ *
+ * @example
+ * ```ts
+ * const { transport } = useGrpc()
+ * const client = new AuthServiceClient(transport.value)
+ * ```
+ */
+export function useGrpc() {
+  const transport: Ref<RpcTransport | null> = ref(null);
+
+  if (_transport) {
+    transport.value = _transport;
+  }
+
+  return {
+    transport,
+    getTransport,
+    initGrpc,
+  };
+}
+
+export type { TransportType };

package/src/composables/useSession.ts

@@ -0,0 +1,80 @@
+import { ref, onMounted, onUnmounted } from "vue";
+import type { SessionInfo } from "../types/auth";
+
+/**
+ * Vue composable for session management.
+ *
+ * Provides reactive session list, auto-refresh, and revocation.
+ * The actual gRPC calls are delegated to a callback to keep
+ * ui-core independent of specific proto client versions.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useSession } from '@structured-id/ui-core'
+ *
+ * const { sessions, loading, refresh } = useSession({
+ *   fetchSessions: async () => { ... },
+ *   revokeSession: async (id) => { ... },
+ * })
+ * </script>
+ * ```
+ */
+export interface SessionCallbacks {
+  fetchSessions: () => Promise<SessionInfo[]>;
+  revokeSession: (sessionId: string) => Promise<void>;
+}
+
+export function useSession(callbacks: SessionCallbacks) {
+  const sessions = ref<SessionInfo[]>([]);
+  const loading = ref(false);
+  const error = ref<string | null>(null);
+  let refreshTimer: ReturnType<typeof setInterval> | null = null;
+
+  async function refresh(): Promise<void> {
+    loading.value = true;
+    error.value = null;
+    try {
+      sessions.value = await callbacks.fetchSessions();
+    } catch (e) {
+      error.value = e instanceof Error ? e.message : String(e);
+    } finally {
+      loading.value = false;
+    }
+  }
+
+  async function revoke(sessionId: string): Promise<void> {
+    await callbacks.revokeSession(sessionId);
+    sessions.value = sessions.value.filter((s) => s.id !== sessionId);
+  }
+
+  function startAutoRefresh(intervalMs = 30_000): void {
+    stopAutoRefresh();
+    refreshTimer = setInterval(refresh, intervalMs);
+  }
+
+  function stopAutoRefresh(): void {
+    if (refreshTimer) {
+      clearInterval(refreshTimer);
+      refreshTimer = null;
+    }
+  }
+
+  onMounted(() => {
+    refresh();
+  });
+
+  onUnmounted(() => {
+    stopAutoRefresh();
+  });
+
+  return {
+    sessions,
+    loading,
+    error,
+    refresh,
+    revoke,
+    startAutoRefresh,
+    stopAutoRefresh,
+  };
+}