@structured-id/ui-core 0.1.5

package/src/utils/normalizePrincipal.ts

@@ -0,0 +1,159 @@
+import parsePhoneNumberFromString, {
+  isValidPhoneNumber,
+} from "libphonenumber-js";
+
+export type LoginInputType = "email" | "phone" | "username" | "unknown";
+
+export interface NormalizedPrincipal {
+  /** Normalized value for storage, uniqueness check, and login lookup. */
+  value: string;
+  /** Original display form (mixed case preserved for usernames). */
+  display: string;
+  type: LoginInputType;
+}
+
+/**
+ * Global username rules per arch/identity/identity-model.md:
+ *   Display:    ^[a-zA-Z0-9_]{3,32}$ — user's original input, mixed case preserved
+ *   Normalized: ^[a-z0-9_]{3,32}$    — lowercase, for storage + uniqueness + login
+ *   - cannot start or end with underscore
+ *   - no consecutive underscores (__)
+ *
+ * For detection (prematch) we use a relaxed version:
+ *   - accepts minLength (3 for login, 6 for registration)
+ *   - case-insensitive (will be lowercased on normalization)
+ */
+const USERNAME_MAX_LENGTH = 32;
+
+/**
+ * Detect principal type from user input.
+ *
+ * Priority: phone (+...) > email (@) > username (alphanumeric).
+ * Returns "unknown" if input doesn't match any pattern.
+ *
+ * @param minUsernameLength - minimum chars to detect as username (3 for login, 6 for register)
+ */
+export function detectLoginInputType(
+  input: string,
+  minUsernameLength = 3,
+): LoginInputType {
+  const trimmed = input.trim();
+  if (!trimmed) return "unknown";
+
+  if (trimmed.startsWith("+")) return "phone";
+  if (trimmed.includes("@")) return "email";
+
+  // Federated username: login#domain (e.g., alice#acme.corp)
+  // No minUsernameLength — org admin decides login part length
+  if (trimmed.includes("#")) {
+    const hashIdx = trimmed.indexOf("#");
+    const loginPart = trimmed.substring(0, hashIdx);
+    const domainPart = trimmed.substring(hashIdx + 1);
+    if (
+      loginPart.length >= 1 &&
+      loginPart.length <= USERNAME_MAX_LENGTH &&
+      domainPart.length > 0 &&
+      /^[a-zA-Z0-9_]+$/.test(loginPart) &&
+      !loginPart.startsWith("_") &&
+      !loginPart.endsWith("_")
+    ) {
+      return "username";
+    }
+    return "unknown";
+  }
+
+  // Global username: no #, no @, no +
+  const re = new RegExp(
+    `^[a-zA-Z0-9_]{${minUsernameLength},${USERNAME_MAX_LENGTH}}$`,
+  );
+  if (re.test(trimmed) && !trimmed.startsWith("_") && !trimmed.endsWith("_")) {
+    return "username";
+  }
+
+  return "unknown";
+}
+
+/**
+ * Normalize principal value for server submission.
+ *
+ * - Email: lowercase, strip dots before @, strip +aliases
+ * - Phone: E.164 format via libphonenumber-js
+ * - Username: lowercase, validate per arch rules
+ *
+ * @param minUsernameLength - minimum chars for username (3 for login, 6 for register)
+ * Throws if value doesn't pass validation for detected type.
+ */
+export function normalizePrincipal(
+  input: string,
+  minUsernameLength = 3,
+): NormalizedPrincipal {
+  const trimmed = input.trim();
+  const type = detectLoginInputType(trimmed, minUsernameLength);
+
+  switch (type) {
+    case "email": {
+      const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+      if (!emailRegex.test(trimmed)) {
+        throw new Error("Invalid email address");
+      }
+      // Remove dots before @, strip +alias, lowercase
+      const [localRaw, domain] = trimmed.split("@");
+      const local = localRaw.replace(/\./g, "").replace(/\+.*$/, "");
+      const normalized = `${local}@${domain}`.toLowerCase();
+      return { value: normalized, display: normalized, type: "email" };
+    }
+
+    case "phone": {
+      if (!isValidPhoneNumber(trimmed)) {
+        throw new Error("Invalid phone number");
+      }
+      const parsed = parsePhoneNumberFromString(trimmed);
+      if (!parsed) throw new Error("Cannot parse phone number");
+      const e164 = parsed.format("E.164");
+      return { value: e164, display: e164, type: "phone" };
+    }
+
+    case "username": {
+      // Federated username: login#domain
+      if (trimmed.includes("#")) {
+        const hashIdx = trimmed.indexOf("#");
+        const loginPart = trimmed.substring(0, hashIdx).toLowerCase();
+        const domainPart = trimmed.substring(hashIdx + 1).toLowerCase();
+
+        // No minUsernameLength for federated — org admin decides
+        const loginRe = new RegExp(`^[a-z0-9_]{1,${USERNAME_MAX_LENGTH}}$`);
+        if (
+          !loginRe.test(loginPart) ||
+          loginPart.startsWith("_") ||
+          loginPart.endsWith("_") ||
+          loginPart.includes("__")
+        ) {
+          throw new Error("Invalid username");
+        }
+        if (!domainPart || !/^[a-z0-9._-]+$/.test(domainPart)) {
+          throw new Error("Invalid federated domain");
+        }
+        const normalized = `${loginPart}#${domainPart}`;
+        return { value: normalized, display: trimmed, type: "username" };
+      }
+
+      // Global username
+      const normalized = trimmed.toLowerCase();
+      const re = new RegExp(
+        `^[a-z0-9_]{${minUsernameLength},${USERNAME_MAX_LENGTH}}$`,
+      );
+      if (
+        !re.test(normalized) ||
+        normalized.startsWith("_") ||
+        normalized.endsWith("_") ||
+        normalized.includes("__")
+      ) {
+        throw new Error("Invalid username");
+      }
+      return { value: normalized, display: trimmed, type: "username" };
+    }
+
+    default:
+      throw new Error("Cannot determine principal type");
+  }
+}

package/src/utils/validators.test.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect } from "vitest";
+import {
+  isValidEmail,
+  isValidPhone,
+  isValidUuid,
+  isValidUsername,
+  minLength,
+  maxLength,
+  isRequired,
+} from "./validators";
+
+describe("isValidEmail", () => {
+  it("accepts valid emails", () => {
+    expect(isValidEmail("user@example.com")).toBe(true);
+    expect(isValidEmail("a.b+c@d.co")).toBe(true);
+  });
+  it("rejects invalid emails", () => {
+    expect(isValidEmail("")).toBe(false);
+    expect(isValidEmail("noat")).toBe(false);
+    expect(isValidEmail("@no-local.com")).toBe(false);
+    expect(isValidEmail("spaces in@email.com")).toBe(false);
+  });
+});
+
+describe("isValidPhone", () => {
+  it("accepts E.164 format", () => {
+    expect(isValidPhone("+380501234567")).toBe(true);
+    expect(isValidPhone("+14155552671")).toBe(true);
+  });
+  it("rejects non-E.164", () => {
+    expect(isValidPhone("0501234567")).toBe(false);
+    expect(isValidPhone("+0123")).toBe(false);
+    expect(isValidPhone("")).toBe(false);
+  });
+});
+
+describe("isValidUuid", () => {
+  it("accepts valid UUIDs", () => {
+    expect(isValidUuid("550e8400-e29b-41d4-a716-446655440000")).toBe(true);
+    expect(isValidUuid("019577A0-2D3E-7B8E-9F1C-4A5B6C7D8E9F")).toBe(true);
+  });
+  it("rejects invalid UUIDs", () => {
+    expect(isValidUuid("not-a-uuid")).toBe(false);
+    expect(isValidUuid("")).toBe(false);
+  });
+});
+
+describe("isValidUsername", () => {
+  it("accepts valid usernames", () => {
+    expect(isValidUsername("alice")).toBe(true);
+    expect(isValidUsername("bob-123")).toBe(true);
+    expect(isValidUsername("a_b")).toBe(true);
+  });
+  it("rejects invalid usernames", () => {
+    expect(isValidUsername("ab")).toBe(false); // too short
+    expect(isValidUsername("has spaces")).toBe(false);
+    expect(isValidUsername("special!char")).toBe(false);
+  });
+});
+
+describe("minLength / maxLength / isRequired", () => {
+  it("minLength works", () => {
+    expect(minLength("abc", 3)).toBe(true);
+    expect(minLength("ab", 3)).toBe(false);
+  });
+  it("maxLength works", () => {
+    expect(maxLength("abc", 3)).toBe(true);
+    expect(maxLength("abcd", 3)).toBe(false);
+  });
+  it("isRequired works", () => {
+    expect(isRequired("hello")).toBe(true);
+    expect(isRequired("  ")).toBe(false);
+    expect(isRequired("")).toBe(false);
+  });
+});

package/src/utils/validators.ts

@@ -0,0 +1,36 @@
+/** Email validation (RFC 5322 simplified). */
+export function isValidEmail(value: string): boolean {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
+}
+
+/** Phone number validation (E.164 format). */
+export function isValidPhone(value: string): boolean {
+  return /^\+[1-9]\d{6,14}$/.test(value);
+}
+
+/** UUID v4/v7 format validation. */
+export function isValidUuid(value: string): boolean {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(
+    value,
+  );
+}
+
+/** Username validation: letters, numbers, hyphens, underscores, 3-64 chars. */
+export function isValidUsername(value: string): boolean {
+  return /^[a-zA-Z0-9_-]{3,64}$/.test(value);
+}
+
+/** Check minimum length. */
+export function minLength(value: string, min: number): boolean {
+  return value.length >= min;
+}
+
+/** Check maximum length. */
+export function maxLength(value: string, max: number): boolean {
+  return value.length <= max;
+}
+
+/** Check value is not empty/whitespace-only. */
+export function isRequired(value: string): boolean {
+  return value.trim().length > 0;
+}