@structured-id/ui-core 0.1.5

package/src/transport/webtransport.ts

@@ -0,0 +1,323 @@
+/**
+ * WebTransport RPC transport for StructuredID.
+ *
+ * Implements the @protobuf-ts/runtime-rpc RpcTransport interface using
+ * the browser WebTransport API over HTTP/3 (QUIC).
+ *
+ * Each unary RPC opens one bidirectional stream:
+ *   Client → Server: [4B len][RequestHeader] [4B len][request body]
+ *   Server → Client: [4B len][ResponseHeader] [4B len][response body]
+ */
+
+import {
+  Deferred,
+  RpcError,
+  mergeRpcOptions,
+  UnaryCall,
+} from "@protobuf-ts/runtime-rpc";
+import type {
+  RpcTransport,
+  MethodInfo,
+  RpcOptions,
+  RpcMetadata,
+  RpcStatus,
+  ServerStreamingCall,
+  ClientStreamingCall,
+  DuplexStreamingCall,
+} from "@protobuf-ts/runtime-rpc";
+import {
+  RequestHeader,
+  ResponseHeader,
+} from "../generated/sid/v1/common/transport";
+import { FrameReader, writeFrame } from "./framing";
+
+export interface WebTransportConnectOptions {
+  /** WebTransport server URL, e.g. "https://localhost:4433" */
+  url: string;
+  /**
+   * SHA-256 certificate hash (hex string) for dev self-signed certs.
+   * Required for connecting to servers with self-signed certificates.
+   */
+  certHash?: string;
+}
+
+/**
+ * Managed WebTransport connection with lazy connect and auto-reconnect detection.
+ */
+export class WebTransportConnection {
+  private transport: WebTransport | null = null;
+  private connecting: Promise<WebTransport> | null = null;
+  private readonly opts: WebTransportConnectOptions;
+
+  constructor(opts: WebTransportConnectOptions) {
+    this.opts = opts;
+  }
+
+  get connected(): boolean {
+    return this.transport !== null;
+  }
+
+  async connect(): Promise<WebTransport> {
+    if (this.transport) return this.transport;
+    if (this.connecting) return this.connecting;
+
+    this.connecting = this.doConnect();
+    return this.connecting;
+  }
+
+  close(): void {
+    if (this.transport) {
+      this.transport.close();
+      this.transport = null;
+    }
+    this.connecting = null;
+  }
+
+  private async doConnect(): Promise<WebTransport> {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const initOpts: Record<string, any> = {};
+
+    if (this.opts.certHash) {
+      const hashBytes = hexToBytes(this.opts.certHash);
+      initOpts.serverCertificateHashes = [
+        { algorithm: "sha-256", value: hashBytes.buffer },
+      ];
+    }
+
+    try {
+      const wt = new WebTransport(this.opts.url, initOpts);
+      await wt.ready;
+
+      this.transport = wt;
+      this.connecting = null;
+
+      wt.closed.then(() => {
+        if (this.transport === wt) {
+          this.transport = null;
+        }
+      });
+
+      return wt;
+    } catch (err) {
+      // Reset so that subsequent connect() calls retry rather than returning
+      // the stale rejected promise.
+      this.connecting = null;
+      throw err;
+    }
+  }
+}
+
+/**
+ * RpcTransport implementation using WebTransport bidirectional streams.
+ *
+ * Requires an established WebTransportConnection — does NOT manage
+ * the connection lifecycle. Use AdaptiveRpcTransport for automatic
+ * failover and reconnect.
+ */
+export class WebTransportRpcTransport implements RpcTransport {
+  private readonly defaultOptions: RpcOptions;
+  private readonly connection: WebTransportConnection;
+
+  constructor(connection: WebTransportConnection, defaultOptions?: RpcOptions) {
+    this.connection = connection;
+    this.defaultOptions = defaultOptions ?? {};
+  }
+
+  mergeOptions(options?: Partial<RpcOptions>): RpcOptions {
+    return mergeRpcOptions(this.defaultOptions, options);
+  }
+
+  unary<I extends object, O extends object>(
+    method: MethodInfo<I, O>,
+    input: I,
+    options: RpcOptions,
+  ): UnaryCall<I, O> {
+    const defHeader = new Deferred<RpcMetadata>();
+    const defMessage = new Deferred<O>();
+    const defStatus = new Deferred<RpcStatus>();
+    const defTrailer = new Deferred<RpcMetadata>();
+
+    this.executeUnary(
+      method,
+      input,
+      options,
+      defHeader,
+      defMessage,
+      defStatus,
+      defTrailer,
+    );
+
+    return new UnaryCall(
+      method,
+      options.meta ?? {},
+      input,
+      defHeader.promise,
+      defMessage.promise,
+      defStatus.promise,
+      defTrailer.promise,
+    );
+  }
+
+  serverStreaming<I extends object, O extends object>(
+    _method: MethodInfo<I, O>,
+    _input: I,
+    _options: RpcOptions,
+  ): ServerStreamingCall<I, O> {
+    throw new RpcError(
+      "Server streaming not supported over WebTransport transport",
+    );
+  }
+
+  clientStreaming<I extends object, O extends object>(
+    _method: MethodInfo<I, O>,
+    _options: RpcOptions,
+  ): ClientStreamingCall<I, O> {
+    throw new RpcError(
+      "Client streaming not supported over WebTransport transport",
+    );
+  }
+
+  duplex<I extends object, O extends object>(
+    _method: MethodInfo<I, O>,
+    _options: RpcOptions,
+  ): DuplexStreamingCall<I, O> {
+    throw new RpcError(
+      "Duplex streaming not supported over WebTransport transport",
+    );
+  }
+
+  private async executeUnary<I extends object, O extends object>(
+    method: MethodInfo<I, O>,
+    input: I,
+    options: RpcOptions,
+    defHeader: Deferred<RpcMetadata>,
+    defMessage: Deferred<O>,
+    defStatus: Deferred<RpcStatus>,
+    defTrailer: Deferred<RpcMetadata>,
+  ): Promise<void> {
+    try {
+      if (!this.connection.connected) {
+        throw new RpcError(
+          "WebTransport connection not established",
+          "UNAVAILABLE",
+        );
+      }
+
+      const wt = await this.connection.connect();
+      const stream = await wt.createBidirectionalStream();
+      const writer = stream.writable.getWriter();
+      const reader = stream.readable.getReader();
+
+      try {
+        // Build RequestHeader
+        const methodPath = `${method.service.typeName}/${method.name}`;
+        const metadata: Record<string, string> = {};
+        if (options.meta) {
+          for (const [key, value] of Object.entries(options.meta)) {
+            if (typeof value === "string") {
+              metadata[key] = value;
+            } else if (Array.isArray(value)) {
+              metadata[key] = value.join(",");
+            }
+          }
+        }
+
+        let timeoutMs = 0;
+        if (options.timeout) {
+          timeoutMs =
+            options.timeout instanceof Date
+              ? Math.max(0, options.timeout.getTime() - Date.now())
+              : options.timeout;
+        }
+
+        const reqHeader: RequestHeader = {
+          method: methodPath,
+          metadata,
+          timeoutMs,
+        };
+
+        // Send RequestHeader + request body
+        const headerBytes = RequestHeader.toBinary(reqHeader);
+        await writeFrame(writer, headerBytes);
+
+        const bodyBytes = method.I.toBinary(input, options.binaryOptions);
+        await writeFrame(writer, bodyBytes);
+
+        // Read ResponseHeader + response body via FrameReader so that excess
+        // bytes from one read() are not lost when reading the next frame.
+        const frameReader = new FrameReader(reader);
+        const respHeaderBytes = await frameReader.readFrame();
+        const respHeader = ResponseHeader.fromBinary(respHeaderBytes);
+
+        const responseHeaders: RpcMetadata = { ...respHeader.metadata };
+        defHeader.resolve(responseHeaders);
+
+        if (respHeader.statusCode !== 0) {
+          throw new RpcError(
+            respHeader.statusMessage || "RPC error",
+            grpcCodeName(respHeader.statusCode),
+          );
+        }
+
+        // Read response body
+        const respBodyBytes = await frameReader.readFrame();
+        const message = method.O.fromBinary(
+          respBodyBytes,
+          options.binaryOptions,
+        );
+
+        defMessage.resolve(message);
+        defStatus.resolve({ code: "OK", detail: "" });
+        defTrailer.resolve({});
+      } finally {
+        writer.releaseLock();
+        reader.releaseLock();
+      }
+    } catch (err) {
+      const rpcErr =
+        err instanceof RpcError
+          ? err
+          : new RpcError(
+              err instanceof Error ? err.message : String(err),
+              "INTERNAL",
+            );
+      defHeader.rejectPending(rpcErr);
+      defMessage.rejectPending(rpcErr);
+      defStatus.rejectPending(rpcErr);
+      defTrailer.rejectPending(rpcErr);
+    }
+  }
+}
+
+/** Convert hex string to Uint8Array. */
+function hexToBytes(hex: string): Uint8Array {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < hex.length; i += 2) {
+    bytes[i / 2] = parseInt(hex.substring(i, i + 2), 16);
+  }
+  return bytes;
+}
+
+/** Map gRPC numeric status code to string name. */
+function grpcCodeName(code: number): string {
+  const names: Record<number, string> = {
+    0: "OK",
+    1: "CANCELLED",
+    2: "UNKNOWN",
+    3: "INVALID_ARGUMENT",
+    4: "DEADLINE_EXCEEDED",
+    5: "NOT_FOUND",
+    6: "ALREADY_EXISTS",
+    7: "PERMISSION_DENIED",
+    8: "RESOURCE_EXHAUSTED",
+    9: "FAILED_PRECONDITION",
+    10: "ABORTED",
+    11: "OUT_OF_RANGE",
+    12: "UNIMPLEMENTED",
+    13: "INTERNAL",
+    14: "UNAVAILABLE",
+    15: "DATA_LOSS",
+    16: "UNAUTHENTICATED",
+  };
+  return names[code] ?? "UNKNOWN";
+}

package/src/types/auth.ts

@@ -0,0 +1,58 @@
+/** Authentication state for the current user session (BFF cookie mode). */
+export interface AuthState {
+  /** Whether a valid BFF session exists. */
+  sessionValid: boolean;
+  /** Server-side session identifier (for step-up, session management). */
+  sessionId: string | null;
+  /** Profile ID of the authenticated user (UUID). */
+  profileId: string | null;
+  /** Display name of the authenticated user. */
+  displayName: string | null;
+  /** Email address (may be null if not in session claims). */
+  email: string | null;
+  /** Preferred username or email — display identifier. */
+  preferredUsername: string | null;
+}
+
+/** Session information as displayed in the dashboard. */
+export interface SessionInfo {
+  id: string;
+  deviceName: string;
+  ipAddress: string;
+  location: string | null;
+  lastActive: string;
+  createdAt: string;
+  current: boolean;
+}
+
+/** gRPC connection configuration. */
+export interface GrpcConfig {
+  /** Base URL for gRPC-web transport (e.g., "https://api.example.com"). */
+  baseUrl: string;
+  /**
+   * @deprecated BFF mode always uses credentials: "include".
+   * This field is kept for API compatibility but has no effect.
+   */
+  withCredentials?: boolean;
+  /**
+   * WebTransport server URL (e.g., "https://wt.api.example.com").
+   * When provided, AdaptiveRpcTransport is used with WebTransport as primary
+   * and gRPC-web as fallback. Omit to use gRPC-web only.
+   */
+  webTransportUrl?: string;
+  /**
+   * SHA-256 certificate hash (hex string) for dev self-signed WebTransport certs.
+   * Only needed when connecting to servers with self-signed certificates.
+   */
+  webTransportCertHash?: string;
+  /**
+   * Delay in milliseconds before attempting to reconnect WebTransport after failover.
+   * Defaults to 5000ms.
+   */
+  webTransportReconnectDelay?: number;
+  /**
+   * Callback fired when the active transport changes between "webtransport" and "grpc-web".
+   * Use this to show transport status indicators in the UI.
+   */
+  onTransportChange?: (transport: "webtransport" | "grpc-web") => void;
+}

package/src/types/index.ts

@@ -0,0 +1 @@
+export type { AuthState, SessionInfo, GrpcConfig } from "./auth";

package/src/utils/formatters.test.ts

@@ -0,0 +1,26 @@
+import { describe, it, expect } from "vitest";
+import { truncate, maskEmail } from "./formatters";
+
+describe("truncate", () => {
+  it("returns original if under max", () => {
+    expect(truncate("hello", 10)).toBe("hello");
+  });
+  it("truncates with ellipsis", () => {
+    expect(truncate("hello world", 6)).toBe("hello\u2026");
+  });
+  it("handles exact length", () => {
+    expect(truncate("hello", 5)).toBe("hello");
+  });
+});
+
+describe("maskEmail", () => {
+  it("masks middle of local part", () => {
+    expect(maskEmail("alice@example.com")).toBe("a***e@example.com");
+  });
+  it("handles short local part", () => {
+    expect(maskEmail("ab@example.com")).toBe("ab@example.com");
+  });
+  it("limits mask to 3 stars", () => {
+    expect(maskEmail("alexander@example.com")).toBe("a***r@example.com");
+  });
+});

package/src/utils/formatters.ts

@@ -0,0 +1,69 @@
+/**
+ * Format a date string or timestamp to locale-aware display.
+ * Falls back to ISO string if Intl is not available.
+ */
+export function formatDate(
+  value: string | number | Date,
+  locale = "en",
+): string {
+  const date = value instanceof Date ? value : new Date(value);
+  if (isNaN(date.getTime())) return String(value);
+
+  try {
+    return new Intl.DateTimeFormat(locale, {
+      year: "numeric",
+      month: "short",
+      day: "numeric",
+      hour: "2-digit",
+      minute: "2-digit",
+    }).format(date);
+  } catch {
+    return date.toISOString();
+  }
+}
+
+/**
+ * Format a relative time (e.g., "5 minutes ago").
+ * Uses Intl.RelativeTimeFormat when available.
+ */
+export function formatRelativeTime(
+  date: string | number | Date,
+  locale = "en",
+): string {
+  const now = Date.now();
+  const then = date instanceof Date ? date.getTime() : new Date(date).getTime();
+  const diffSeconds = Math.floor((now - then) / 1000);
+
+  if (diffSeconds < 60) return locale === "uk" ? "Щойно" : "Just now";
+
+  try {
+    const rtf = new Intl.RelativeTimeFormat(locale, { numeric: "auto" });
+
+    if (diffSeconds < 3600) {
+      return rtf.format(-Math.floor(diffSeconds / 60), "minute");
+    }
+    if (diffSeconds < 86400) {
+      return rtf.format(-Math.floor(diffSeconds / 3600), "hour");
+    }
+    return rtf.format(-Math.floor(diffSeconds / 86400), "day");
+  } catch {
+    const minutes = Math.floor(diffSeconds / 60);
+    if (minutes < 60) return `${minutes}m ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24) return `${hours}h ago`;
+    return `${Math.floor(hours / 24)}d ago`;
+  }
+}
+
+/** Truncate a string with ellipsis. */
+export function truncate(value: string, maxLen: number): string {
+  if (value.length <= maxLen) return value;
+  return value.slice(0, maxLen - 1) + "\u2026";
+}
+
+/** Mask an email address for display (e.g., "a***e@example.com"). */
+export function maskEmail(email: string): string {
+  const [local, domain] = email.split("@");
+  if (!domain || local.length <= 2) return email;
+  return `${local[0]}${"*".repeat(Math.min(local.length - 2, 3))}${local[local.length - 1]}@${domain}`;
+}

package/src/utils/index.ts

@@ -0,0 +1,16 @@
+export {
+  isValidEmail,
+  isValidPhone,
+  isValidUuid,
+  isValidUsername,
+  minLength,
+  maxLength,
+  isRequired,
+} from "./validators";
+
+export {
+  formatDate,
+  formatRelativeTime,
+  truncate,
+  maskEmail,
+} from "./formatters";

package/src/utils/normalizePrincipal.test.ts

@@ -0,0 +1,188 @@
+import { describe, it, expect } from "vitest";
+import { detectLoginInputType, normalizePrincipal } from "./normalizePrincipal";
+
+describe("detectLoginInputType", () => {
+  it("detects email", () => {
+    expect(detectLoginInputType("alice@example.com")).toBe("email");
+    expect(detectLoginInputType("user+tag@mail.co")).toBe("email");
+  });
+
+  it("detects phone", () => {
+    expect(detectLoginInputType("+380501234567")).toBe("phone");
+    expect(detectLoginInputType("+1555")).toBe("phone");
+  });
+
+  it("detects username (default minLength=3)", () => {
+    expect(detectLoginInputType("sid")).toBe("username");
+    expect(detectLoginInputType("alice")).toBe("username");
+    expect(detectLoginInputType("bob_smith")).toBe("username");
+    expect(detectLoginInputType("dev42")).toBe("username");
+    // Uppercase accepted in detection (will be lowercased on normalize)
+    expect(detectLoginInputType("Admin123")).toBe("username");
+  });
+
+  it("detects username with minLength=6 (registration)", () => {
+    expect(detectLoginInputType("alice", 6)).toBe("unknown"); // too short
+    expect(detectLoginInputType("alicew", 6)).toBe("username"); // exactly 6
+    expect(detectLoginInputType("alice_wonder", 6)).toBe("username");
+  });
+
+  it("rejects usernames starting/ending with underscore", () => {
+    expect(detectLoginInputType("_alice")).toBe("unknown");
+    expect(detectLoginInputType("alice_")).toBe("unknown");
+  });
+
+  it("accepts digits in username (arch allows ^[a-z0-9_])", () => {
+    expect(detectLoginInputType("1abc")).toBe("username"); // digit start is OK per arch
+    expect(detectLoginInputType("42dev")).toBe("username");
+  });
+
+  it("rejects username exceeding max length (32)", () => {
+    const long = "a".repeat(33);
+    expect(detectLoginInputType(long)).toBe("unknown");
+    // Exactly 32 is OK
+    expect(detectLoginInputType("a".repeat(32))).toBe("username");
+  });
+
+  it("returns unknown for empty or whitespace input", () => {
+    expect(detectLoginInputType("")).toBe("unknown");
+    expect(detectLoginInputType("  ")).toBe("unknown");
+    expect(detectLoginInputType("ab")).toBe("unknown"); // too short (default min=3)
+  });
+
+  it("phone takes priority over username for +", () => {
+    expect(detectLoginInputType("+abc")).toBe("phone");
+  });
+
+  it("email takes priority for @", () => {
+    expect(detectLoginInputType("a@b")).toBe("email");
+  });
+
+  // ── Federated username (user#domain) ──
+
+  it("detects federated username", () => {
+    expect(detectLoginInputType("alice#acme.corp")).toBe("username");
+    expect(detectLoginInputType("bob#example.com")).toBe("username");
+    expect(detectLoginInputType("dev42#internal.net")).toBe("username");
+  });
+
+  it("detects federated username with uppercase", () => {
+    expect(detectLoginInputType("Alice#Acme.Corp")).toBe("username");
+  });
+
+  it("accepts short login part in federated username (org admin decides)", () => {
+    expect(detectLoginInputType("ab#acme.corp")).toBe("username"); // 2 chars OK
+    expect(detectLoginInputType("a#acme.corp")).toBe("username"); // 1 char OK
+  });
+
+  it("rejects federated username with empty login part", () => {
+    expect(detectLoginInputType("#acme.corp")).toBe("unknown");
+  });
+
+  it("rejects federated username with empty domain", () => {
+    expect(detectLoginInputType("alice#")).toBe("unknown");
+  });
+
+  it("rejects federated username with leading underscore in login part", () => {
+    expect(detectLoginInputType("_alice#acme.corp")).toBe("unknown");
+  });
+
+  it("# takes priority over plain username detection", () => {
+    expect(detectLoginInputType("alice#domain")).toBe("username");
+  });
+
+  it("ignores minUsernameLength for federated username", () => {
+    // minUsernameLength=6 only applies to global usernames, not federated
+    expect(detectLoginInputType("alice#acme.corp", 6)).toBe("username"); // 5 chars OK
+    expect(detectLoginInputType("ab#acme.corp", 6)).toBe("username"); // 2 chars OK
+  });
+});
+
+describe("normalizePrincipal", () => {
+  it("normalizes email: lowercase + strip dots + strip alias", () => {
+    const result = normalizePrincipal("Alice.Bob+tag@Example.COM");
+    expect(result.type).toBe("email");
+    expect(result.value).toBe("alicebob@example.com");
+    expect(result.display).toBe("alicebob@example.com");
+  });
+
+  it("normalizes phone to E.164", () => {
+    const result = normalizePrincipal("+380 50 123 45 67");
+    expect(result.type).toBe("phone");
+    expect(result.value).toBe("+380501234567");
+    expect(result.display).toBe("+380501234567");
+  });
+
+  it("normalizes username: value=lowercase, display=original casing", () => {
+    const result = normalizePrincipal("Alice_Bob");
+    expect(result.type).toBe("username");
+    expect(result.value).toBe("alice_bob");
+    expect(result.display).toBe("Alice_Bob");
+  });
+
+  it("rejects username with leading/trailing underscore (detected as unknown)", () => {
+    // Leading/trailing _ blocked at detection level → "Cannot determine"
+    expect(() => normalizePrincipal("_alice_bob")).toThrow("Cannot determine");
+    expect(() => normalizePrincipal("alice_")).toThrow("Cannot determine");
+  });
+
+  it("rejects username with consecutive underscores", () => {
+    // Detected as username (passes detection regex), but fails validation
+    expect(() => normalizePrincipal("alice__bob")).toThrow("Invalid username");
+  });
+
+  it("respects minUsernameLength for registration (6)", () => {
+    // 5-char username OK with default (3) but fails with minLength=6
+    expect(normalizePrincipal("alice").type).toBe("username");
+    expect(() => normalizePrincipal("alice", 6)).toThrow("Cannot determine");
+  });
+
+  it("throws on invalid email", () => {
+    expect(() => normalizePrincipal("alice@")).toThrow("Invalid email");
+  });
+
+  it("throws on invalid phone", () => {
+    expect(() => normalizePrincipal("+000")).toThrow("Invalid phone");
+  });
+
+  it("throws on unknown type", () => {
+    expect(() => normalizePrincipal("ab")).toThrow("Cannot determine");
+  });
+
+  // ── Federated username normalization ──
+
+  it("normalizes federated username: lowercase both parts", () => {
+    const result = normalizePrincipal("Alice#Acme.Corp");
+    expect(result.type).toBe("username");
+    expect(result.value).toBe("alice#acme.corp");
+    expect(result.display).toBe("Alice#Acme.Corp");
+  });
+
+  it("normalizes federated username with numbers", () => {
+    const result = normalizePrincipal("dev42#internal.net");
+    expect(result.type).toBe("username");
+    expect(result.value).toBe("dev42#internal.net");
+  });
+
+  it("rejects federated username with consecutive underscores in login part", () => {
+    expect(() => normalizePrincipal("alice__bob#acme.corp")).toThrow(
+      "Invalid username",
+    );
+  });
+
+  it("rejects federated username with invalid domain chars", () => {
+    expect(() => normalizePrincipal("alice#acme corp")).toThrow(
+      "Invalid federated domain",
+    );
+  });
+
+  it("rejects federated username with empty domain", () => {
+    expect(() => normalizePrincipal("alice#")).toThrow("Cannot determine");
+  });
+
+  it("preserves display form for federated username", () => {
+    const result = normalizePrincipal("Bob_Smith#MyCompany.com");
+    expect(result.display).toBe("Bob_Smith#MyCompany.com");
+    expect(result.value).toBe("bob_smith#mycompany.com");
+  });
+});