@structured-id/ui-core 4.1.0 → 4.3.0

package/src/quasar/SidPrincipalInput.vue

@@ -3,7 +3,7 @@
     ref="inputRef"
     v-model="model"
     :label="fieldLabel"
-    :rules="[requiredRule, typeRule]"
+    :rules="[typeRule]"
     :error="!!fieldError"
     :error-message="fieldError ?? undefined"
     outlined
@@ -18,7 +18,7 @@
     <template #prepend>
       <q-icon :name="iconName" :color="iconColor" size="24px" />
     </template>
-    <template v-if="model && detectedType !== 'unknown'" #append>
+    <template v-if="showChip" #append>
       <q-chip
         dense
         :color="chipColor"
@@ -35,11 +35,12 @@
 <script setup lang="ts">
 import { ref, computed, watch } from "vue";
 import { isValidPhoneNumber } from "libphonenumber-js";
-import { REQUIRED_FIELD_TEXT, isValidEmail } from "../utils/validators";
+import { checkEmail, emailReady, initEmail } from "../utils/email";
 
 import {
   ALL_PRINCIPAL_TYPES,
   DEFAULT_PRINCIPAL_INPUT_TEXTS,
+  principalRecognizable,
   type AcceptedPrincipalType,
   type PrincipalInputTexts,
   type PrincipalType,
@@ -56,15 +57,12 @@ interface Props {
    */
   types?: AcceptedPrincipalType[];
   minUsernameLength?: number;
-  required?: boolean;
   /** The label; without one the field names the accepted types. */
   label?: string;
   /** A refusal the server bound to this field, shown on it until edited. */
   fieldError?: string | null;
   /** Replacements for the field's texts. */
   texts?: Partial<PrincipalInputTexts>;
-  /** What an empty required field says. */
-  requiredText?: string;
   /**
    * Validate once the field is left, then on every change (true), or on
    * every change from the first keystroke (false). Default true: a field
@@ -76,13 +74,11 @@ interface Props {
 const props = withDefaults(defineProps<Props>(), {
   modelValue: "",
   types: () => [...ALL_PRINCIPAL_TYPES],
-  // Username rule: ^[a-z0-9_]{3,32}$ (display form ^[a-zA-Z0-9_]{3,32}$).
+  // Code points of the NFC display form; the server's minimum decides.
   minUsernameLength: 3,
-  required: true,
   label: undefined,
   fieldError: null,
   texts: () => ({}),
-  requiredText: REQUIRED_FIELD_TEXT,
   lazyRules: true,
 });
 
@@ -96,13 +92,26 @@ const accepted = computed(() =>
   ALL_PRINCIPAL_TYPES.filter((t) => props.types.includes(t)),
 );
 
-const fieldLabel = computed(
-  () => props.label ?? text.value.label(accepted.value),
-);
+/**
+ * A field of one type is named by it; a field of several is a login field
+ * until its input is recognized as one of the accepted types.
+ */
+const fieldLabel = computed(() => {
+  // An empty label is the form's own choice; only an absent one is derived.
+  if (props.label != null) return props.label;
+  const [only, ...others] = accepted.value;
+  if (only && others.length === 0) return text.value.label([only]);
+  const type = detectedType.value;
+  return type !== "unknown" && accepted.value.includes(type)
+    ? text.value.label([type])
+    : text.value.login;
+});
 
 const emit = defineEmits<{
   "update:modelValue": [value: string];
   "update:principalType": [type: PrincipalType];
+  /** Whether the value can be submitted: a recognized, accepted, well-formed principal. */
+  "update:valid": [valid: boolean];
 }>();
 
 const inputRef = ref<{ focus: () => void } | null>(null);
@@ -114,10 +123,13 @@ const model = computed({
 
 const USERNAME_MAX_LENGTH = 32;
 
+/** What a username may hold: letters of any script, marks, digits, `_`. */
+const USERNAME_SHAPE = /^[\p{L}\p{M}\p{N}_]+$/u;
+
 function detectType(value: string): PrincipalType {
-  if (!value) return "unknown";
+  // One or two characters are nobody yet: no type is read from them.
+  if (!principalRecognizable(value)) return "unknown";
   const trimmed = value.trim();
-  if (!trimmed) return "unknown";
 
   // Phone: starts with +
   if (trimmed.startsWith("+")) return "phone";
@@ -125,12 +137,9 @@ function detectType(value: string): PrincipalType {
   // Email: contains @ (checked after phone to exclude edge cases)
   if (trimmed.includes("@")) return "email";
 
-  // Username by its shape at any length, so that a short one is told the
-  // minimum instead of being taken for no type at all. Uppercase is accepted
-  // (the server derives the key); length and underscores are the rule's.
-  if (/^[a-zA-Z0-9_]+$/.test(trimmed)) return "username";
-
-  return "unknown";
+  // Anything else is a username attempt, whatever it holds, so that what is
+  // wrong with it (spaces, a dot, a symbol, its length) can be said.
+  return "username";
 }
 
 const detectedType = computed(() => detectType(model.value));
@@ -146,26 +155,37 @@ function onInput(value: string | number | null) {
 
 // --- Validation rules ---
 
-const requiredRule = (val: string) =>
-  !props.required || !!val || props.requiredText;
-
+/**
+ * Until a type is recognized nothing is wrong yet, an empty field included:
+ * the form keeps its button disabled instead (see principalRecognizable).
+ */
 const typeRule = (val: string): string | true => {
-  if (!val) return true; // required rule handles empty
   const type = detectType(val);
-  if (type === "unknown" || !accepted.value.includes(type)) {
+  if (type === "unknown") return true;
+  if (!accepted.value.includes(type)) {
     return text.value.enterAccepted(accepted.value);
   }
 
   switch (type) {
-    case "email":
-      return isValidEmail(val.trim()) || text.value.invalidEmail;
+    case "email": {
+      // Read so the rule re-runs once the parser has loaded.
+      void emailReady.value;
+      const check = checkEmail(val.trim());
+      // Nothing is wrong yet while the parser loads; `valid` stays false.
+      return check !== "invalid" || text.value.invalidEmail;
+    }
     case "phone":
       return isValidPhoneNumber(val) || text.value.invalidPhone;
     case "username": {
-      const name = val.trim();
-      if (name.length < props.minUsernameLength)
+      const name = val;
+      if (/\s/u.test(name)) return text.value.usernameSpaces;
+      if (!USERNAME_SHAPE.test(name)) return text.value.usernameCharacters;
+      // Counted in code points of the NFC form, as the server counts the
+      // display; the value itself is sent unchanged.
+      const length = [...name.normalize("NFC")].length;
+      if (length < props.minUsernameLength)
         return text.value.usernameTooShort(props.minUsernameLength);
-      if (name.length > USERNAME_MAX_LENGTH)
+      if (length > USERNAME_MAX_LENGTH)
         return text.value.usernameTooLong(USERNAME_MAX_LENGTH);
       if (name.startsWith("_") || name.endsWith("_"))
         return text.value.usernameUnderscoreEdge;
@@ -175,10 +195,63 @@ const typeRule = (val: string): string | true => {
   }
 };
 
+/**
+ * A form keeps its submit disabled until this holds, silently: the error a
+ * rule names appears only once the field is left, the button never waits for
+ * it. A refusal the server bound to the field holds until the value changes.
+ */
+const valid = computed(
+  () =>
+    detectedType.value !== "unknown" &&
+    typeRule(model.value) === true &&
+    // An email is not submittable before the parser has judged it.
+    (detectedType.value !== "email" || emailReady.value) &&
+    !props.fieldError,
+);
+
+// The application starts the parser at boot (initEmail with its namespace);
+// a field that accepts email starts it when nobody did, also once its
+// accepted types come to include email.
+watch(
+  () => accepted.value.includes("email"),
+  (takesEmail) => {
+    if (takesEmail && !emailReady.value) {
+      initEmail().catch((error: unknown) => {
+        console.error("email address parser failed to load", error);
+      });
+    }
+  },
+  { immediate: true },
+);
+
+watch(valid, (v) => emit("update:valid", v), { immediate: true });
+
 // --- Dynamic icon & type ---
 
+/** The recognized type when the field accepts it; refused types look neutral. */
+const shownType = computed<PrincipalType>(() => {
+  const type = detectedType.value;
+  return type !== "unknown" && accepted.value.includes(type) ? type : "unknown";
+});
+
+/**
+ * The chip names the type only when the label does not: a derived label
+ * already says "Email" or "Username".
+ */
+const showChip = computed(
+  () => props.label != null && shownType.value !== "unknown",
+);
+
+/** A field of one type shows that type's icon from the start, greyed until recognized. */
+const iconType = computed<PrincipalType>(() => {
+  const [only, ...others] = accepted.value;
+  return shownType.value === "unknown" && only && others.length === 0
+    ? only
+    : shownType.value;
+});
+
 const iconName = computed(() => {
-  switch (detectedType.value) {
+  switch (iconType.value) {
     case "email":
       return "sym_o_mail";
     case "phone":
@@ -191,7 +264,7 @@ const iconName = computed(() => {
 });
 
 const iconColor = computed(() =>
-  detectedType.value === "unknown" ? "grey-6" : "primary",
+  shownType.value === "unknown" ? "grey-6" : "primary",
 );
 
 // inputmode controls mobile keyboard WITHOUT triggering browser autofill.
@@ -211,13 +284,11 @@ const inputMode = computed(() => {
 });
 
 const chipLabel = computed(() =>
-  detectedType.value === "unknown"
-    ? ""
-    : text.value.typeChip(detectedType.value),
+  shownType.value === "unknown" ? "" : text.value.typeChip(shownType.value),
 );
 
 const chipColor = computed(() => {
-  switch (detectedType.value) {
+  switch (shownType.value) {
     case "email":
       return "deep-orange";
     case "phone":
@@ -235,5 +306,5 @@ function focus() {
   inputRef.value?.focus();
 }
 
-defineExpose({ focus, detectedType });
+defineExpose({ focus, detectedType, valid });
 </script>

package/src/quasar/index.ts

@@ -13,6 +13,8 @@ export type {
 export {
   ALL_PRINCIPAL_TYPES,
   DEFAULT_PRINCIPAL_INPUT_TEXTS,
+  MIN_PRINCIPAL_LENGTH,
+  principalRecognizable,
 } from "./principalInputTexts";
 export { default as SidPasswordCeremony } from "./SidPasswordCeremony.vue";
 export type { CeremonyOutcome } from "./SidPasswordCeremony.vue";

package/src/quasar/principalInputTexts.ts

@@ -12,10 +12,27 @@ export const ALL_PRINCIPAL_TYPES: readonly AcceptedPrincipalType[] = [
   "username",
 ];
 
+/**
+ * Fewer characters than this are nobody yet: no type is recognized from them
+ * and no form can submit them. Counted in code points of the NFC form,
+ * surrounding whitespace aside.
+ */
+export const MIN_PRINCIPAL_LENGTH = 3;
+
+/** Whether `value` is long enough to be anybody. */
+export function principalRecognizable(value: string): boolean {
+  return [...value.trim().normalize("NFC")].length >= MIN_PRINCIPAL_LENGTH;
+}
+
 /** What the field says; each text can be replaced (translated) by the form. */
 export interface PrincipalInputTexts {
-  /** The label for the accepted types, when the form gives none. */
+  /**
+   * The label naming one type: the field's only accepted type, or the type
+   * the input of a several-type field was recognized as.
+   */
   label: (types: AcceptedPrincipalType[]) => string;
+  /** The label of a field of several types before its input shows which. */
+  login: string;
   /** A value of a type the field does not accept, or of no type at all. */
   enterAccepted: (types: AcceptedPrincipalType[]) => string;
   /** The chip naming the type the value was recognized as. */
@@ -28,6 +45,10 @@ export interface PrincipalInputTexts {
   usernameTooLong: (max: number) => string;
   usernameUnderscoreEdge: string;
   usernameDoubleUnderscore: string;
+  /** A username with whitespace in or around it. */
+  usernameSpaces: string;
+  /** A username with a character other than a letter, digit or `_`. */
+  usernameCharacters: string;
 }
 
 /** `a`, `a or b`, `a, b, or c`. */
@@ -54,6 +75,7 @@ export const DEFAULT_PRINCIPAL_INPUT_TEXTS: PrincipalInputTexts = {
     const text = list(types.map((t) => LABEL_WORDS[t]));
     return text.charAt(0).toUpperCase() + text.slice(1);
   },
+  login: "Login",
   enterAccepted: (types) => `Enter ${list(types.map((t) => ENTER_WORDS[t]))}`,
   typeChip: (type) => LABEL_WORDS[type],
   loginSubtitle: (types) =>
@@ -65,4 +87,7 @@ export const DEFAULT_PRINCIPAL_INPUT_TEXTS: PrincipalInputTexts = {
   usernameUnderscoreEdge: "A username cannot start or end with an underscore",
   usernameDoubleUnderscore:
     "A username cannot contain two underscores in a row",
+  usernameSpaces: "A username cannot contain spaces",
+  usernameCharacters:
+    "A username can contain only letters, digits and underscores",
 };

package/src/utils/email.test.ts

@@ -0,0 +1,107 @@
+import { beforeAll, describe, expect, it } from "vitest";
+import {
+  CORPORATE_BASELINE,
+  GLOBAL_PERSONAL,
+  LOCAL,
+  checkEmail,
+  emailPolicy,
+  initEmail,
+  isValidEmail,
+} from "./email";
+import { TEST_PSL } from "./email.testing";
+
+// The admission the server applies (sid_authn::email): the same parser, the
+// same configuration per namespace, so the field refuses what the server
+// would refuse and accepts what it would accept.
+
+describe("before the parser is loaded", () => {
+  // Nothing is judged without the parser: a hand-written guess would accept
+  // what the server refuses.
+  it("says pending and never valid", () => {
+    expect(checkEmail("user@example.com", LOCAL)).toBe("pending");
+    expect(isValidEmail("user@example.com", LOCAL)).toBe(false);
+  });
+});
+
+describe("with the parser", () => {
+  beforeAll(async () => {
+    await initEmail({ psl: TEST_PSL });
+  });
+
+  it("accepts an ordinary mailbox in every namespace", () => {
+    for (const policy of [GLOBAL_PERSONAL, CORPORATE_BASELINE, LOCAL]) {
+      expect(checkEmail("a.b+c@example.com", policy)).toBe("valid");
+    }
+  });
+
+  it("refuses what is never an address", () => {
+    for (const input of [
+      "",
+      "noat",
+      "@no-local.com",
+      "user@",
+      "spaces in@email.com",
+      "user@exa mple.com",
+    ]) {
+      expect(checkEmail(input, LOCAL), input).toBe("invalid");
+    }
+  });
+
+  // RFC 5321 §4.1.2: a quoted local part is a mailbox; comments and display
+  // names are header syntax and are not.
+  it("accepts a quoted local part, refuses header syntax", () => {
+    expect(checkEmail('"a b"@example.com', LOCAL)).toBe("valid");
+    expect(checkEmail('"a@b"@example.com', LOCAL)).toBe("valid");
+    expect(checkEmail("a(comment)@example.com", LOCAL)).toBe("invalid");
+    expect(checkEmail("Name <a@example.com>", LOCAL)).toBe("invalid");
+  });
+
+  it("refuses a local part left empty by the equality rules", () => {
+    expect(checkEmail("+tag@example.com", LOCAL)).toBe("invalid");
+  });
+
+  describe("the global Personal namespace", () => {
+    it("refuses non-ASCII in either part", () => {
+      expect(checkEmail("алиса@example.com", GLOBAL_PERSONAL)).toBe("invalid");
+      expect(checkEmail("user@münchen.de", GLOBAL_PERSONAL)).toBe("invalid");
+    });
+
+    it("refuses an A-label domain", () => {
+      expect(checkEmail("user@xn--mnchen-3ya.de", GLOBAL_PERSONAL)).toBe(
+        "invalid",
+      );
+    });
+
+    it("requires a public suffix", () => {
+      expect(checkEmail("admin@printer", GLOBAL_PERSONAL)).toBe("invalid");
+      expect(checkEmail("user@example.notatld", GLOBAL_PERSONAL)).toBe(
+        "invalid",
+      );
+    });
+  });
+
+  describe("an installation's own accounts", () => {
+    it("admits internal and internationalized mail domains", () => {
+      expect(checkEmail("admin@printer", LOCAL)).toBe("valid");
+      expect(checkEmail("user@münchen.de", LOCAL)).toBe("valid");
+      expect(checkEmail("алиса@example.com", LOCAL)).toBe("valid");
+    });
+  });
+
+  it("corporate baseline admits an internal domain, ASCII only", () => {
+    expect(checkEmail("admin@printer", CORPORATE_BASELINE)).toBe("valid");
+    expect(checkEmail("user@münchen.de", CORPORATE_BASELINE)).toBe("invalid");
+  });
+});
+
+describe("the application's namespace", () => {
+  it("is LOCAL unless the application names its own", async () => {
+    await initEmail();
+    expect(emailPolicy()).toBe(LOCAL);
+    await initEmail({ policy: GLOBAL_PERSONAL });
+    expect(emailPolicy()).toBe(GLOBAL_PERSONAL);
+    expect(isValidEmail("admin@printer")).toBe(false);
+    await initEmail({ policy: LOCAL });
+    expect(isValidEmail("admin@printer")).toBe(true);
+  });
+});

package/src/utils/email.testing.ts

@@ -0,0 +1,19 @@
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import type { PslSource } from "./email";
+
+/**
+ * The trie the application would serve, read from the installed package, for
+ * tests running without the application's host. Not cached, so a test never
+ * reads another run's copy.
+ */
+export const TEST_PSL: PslSource = {
+  url: "psl.bin",
+  cache: false,
+  fetch: (async () => {
+    const path = createRequire(import.meta.url).resolve(
+      "@structured-world/structured-public-domains/psl.bin",
+    );
+    return new Response(await readFile(path));
+  }) as typeof fetch,
+};

package/src/utils/email.ts

@@ -0,0 +1,165 @@
+// An ambient declaration cannot be imported, and a consumer compiling this
+// source sees it only through this reference.
+// eslint-disable-next-line @typescript-eslint/triple-slash-reference
+/// <reference path="../assets.d.ts" />
+import { readonly, ref, shallowRef, type Ref } from "vue";
+
+/**
+ * Which mailboxes an email namespace admits, as the server's policy for it
+ * (sid_authn::email) does. Equality and the resolution key stay the
+ * server's: the field only refuses what the namespace never admits.
+ */
+export interface EmailPolicy {
+  /** Accept non-ASCII characters in the local part (RFC 6531). */
+  readonly unicodeLocal: boolean;
+  /** Accept internationalized domains, in Unicode or A-label spelling. */
+  readonly idnDomain: boolean;
+  /** Accept a domain without a dot (an installation-local mail domain). */
+  readonly singleLabelDomain: boolean;
+  /** Require the domain to end in a Public Suffix List suffix. */
+  readonly publicSuffix: boolean;
+}
+
+/** The global SaaS/federated Personal namespace: ASCII, no IDN, a public mail domain. */
+export const GLOBAL_PERSONAL: EmailPolicy = Object.freeze({
+  unicodeLocal: false,
+  idnDomain: false,
+  singleLabelDomain: false,
+  publicSuffix: true,
+});
+
+/** An organization's Corporate namespace before it sets its own rules. */
+export const CORPORATE_BASELINE: EmailPolicy = Object.freeze({
+  unicodeLocal: false,
+  idnDomain: false,
+  singleLabelDomain: true,
+  publicSuffix: false,
+});
+
+/** An installation's own managed accounts (standalone). */
+export const LOCAL: EmailPolicy = Object.freeze({
+  unicodeLocal: true,
+  idnDomain: true,
+  singleLabelDomain: true,
+  publicSuffix: false,
+});
+
+/** A verdict on one input; `pending` until the parser is loaded. */
+export type EmailCheck = "valid" | "invalid" | "pending";
+
+type Parser = typeof import("@structured-world/structured-email-address-ts");
+
+/** How the Public Suffix List trie is fetched and cached. */
+export type PslSource = NonNullable<
+  NonNullable<Parameters<Parser["init"]>[0]>["psl"]
+>;
+
+let parser: Parser | undefined;
+let loading: Promise<Parser> | undefined;
+// Reactive, so a verdict computed under it is recomputed when it changes.
+const appPolicy = shallowRef<EmailPolicy>(LOCAL);
+const loaded = ref(false);
+
+/** Whether the parser is loaded; a rule depending on it re-runs when it is. */
+export const emailReady: Readonly<Ref<boolean>> = readonly(loaded);
+
+/**
+ * The trie this package ships, as the application's own asset: the bundler
+ * emits it beside the bundle, so the application's host serves it.
+ */
+async function bundledPsl(): Promise<string> {
+  const asset =
+    await import("@structured-world/structured-public-domains/psl.bin?url");
+  return asset.default;
+}
+
+/**
+ * Load the parser (once) and set the application's email namespace, LOCAL
+ * unless named. The parser is the TypeScript port of the server's, checked
+ * byte-identical against it; its Public Suffix List trie comes from `psl`
+ * (`url`: the setting of where it is served, the application's own copy of
+ * it when unset; never a third-party CDN), cached in IndexedDB. An
+ * application calls this at start; a field starts it when nobody did.
+ */
+export async function initEmail(options?: {
+  policy?: EmailPolicy;
+  psl?: PslSource;
+}): Promise<void> {
+  if (options?.policy) appPolicy.value = options.policy;
+  loading ??= import("@structured-world/structured-email-address-ts").then(
+    async (module) => {
+      const url = options?.psl?.url ?? (await bundledPsl());
+      await module.init({ psl: { ...options?.psl, url } });
+      return module;
+    },
+  );
+  try {
+    parser = await loading;
+  } catch (error) {
+    // A failed load is retried by the next call, never cached as loaded.
+    loading = undefined;
+    throw error;
+  }
+  loaded.value = true;
+}
+
+/** The application's email namespace. */
+export function emailPolicy(): EmailPolicy {
+  return appPolicy.value;
+}
+
+/** Whether a domain label is an IDNA A-label (`xn--`). */
+function isALabel(label: string): boolean {
+  return label.slice(0, 4).toLowerCase() === "xn--";
+}
+
+/**
+ * Whether `value` is one mailbox the namespace admits: an RFC 5321 mailbox
+ * (dot-atom or quoted local part; no comments, display name or address
+ * literal) under the namespace's character, domain and suffix rules, with a
+ * local part that its equality rules (case, dots, `+tag`) do not empty.
+ */
+export function checkEmail(
+  value: string,
+  policy: EmailPolicy = appPolicy.value,
+): EmailCheck {
+  if (!parser) return "pending";
+  if (
+    !policy.unicodeLocal &&
+    !policy.idnDomain &&
+    !/^[\x00-\x7f]*$/.test(value)
+  ) {
+    return "invalid";
+  }
+  let local: string;
+  let domain: string;
+  try {
+    const mailbox = parser.parse(value, {
+      strictness: "strict",
+      allowQuotedLocalPart: true,
+      casePolicy: "preserve",
+      dotPolicy: "preserve",
+      subaddress: "preserve",
+      allowSingleLabelDomain: policy.singleLabelDomain,
+      domainCheck: policy.publicSuffix ? "psl" : "syntax",
+    });
+    local = mailbox.localPart;
+    domain = mailbox.domain;
+  } catch {
+    return "invalid";
+  }
+  if (!policy.unicodeLocal && !/^[\x00-\x7f]*$/.test(local)) return "invalid";
+  // A Unicode domain arrives IDNA-encoded, so A-labels cover both spellings.
+  if (!policy.idnDomain && domain.split(".").some(isALabel)) return "invalid";
+  const base = local.toLowerCase().split("+", 1)[0] ?? "";
+  if (base.replaceAll(".", "") === "") return "invalid";
+  return "valid";
+}
+
+/** {@link checkEmail} as a yes/no; `false` while the parser is loading. */
+export function isValidEmail(
+  value: string,
+  policy: EmailPolicy = appPolicy.value,
+): boolean {
+  return checkEmail(value, policy) === "valid";
+}

package/src/utils/index.ts

@@ -1,5 +1,4 @@
 export {
-  isValidEmail,
   isValidPhone,
   isValidUuid,
   isValidUsername,
@@ -8,6 +7,19 @@ export {
   isRequired,
 } from "./validators";
 
+export {
+  CORPORATE_BASELINE,
+  GLOBAL_PERSONAL,
+  LOCAL,
+  checkEmail,
+  emailPolicy,
+  emailReady,
+  initEmail,
+  isValidEmail,
+  type EmailCheck,
+  type EmailPolicy,
+} from "./email";
+
 export {
   formatDate,
   formatRelativeTime,