@structured-id/ui-core 0.1.5

package/src/profile/composables/useOpaqueAuth.ts

@@ -0,0 +1,191 @@
+/**
+ * OPAQUE auth flow orchestration (shared between all profile UIs).
+ *
+ * Uses dependency injection for client-side crypto: apps provide an
+ * OpaqueClientApi implementation (from @structured-id/opaque), keeping
+ * the WASM dependency at the app layer.
+ *
+ * gRPC calls go through useAuthApi wrappers.
+ */
+import {
+  opaqueLoginStart,
+  opaqueLoginFinish,
+  opaqueRegistrationStart,
+  opaqueRegistrationFinish,
+} from "./useAuthApi";
+
+// ── Types ──
+
+export interface LoginResult {
+  sessionId: string;
+  accessToken: string;
+  expiresIn: number;
+}
+
+export interface RegisterResult {
+  profileId: string;
+  credentialId: string;
+}
+
+/**
+ * Interface for OPAQUE client-side crypto operations.
+ * Implemented by @structured-id/opaque OpaqueClient.
+ */
+export interface OpaqueClientApi {
+  loginStart(password: string): Promise<{ ke1: Uint8Array; state: unknown }>;
+  loginFinish(
+    password: string,
+    ke2: Uint8Array,
+    state: unknown,
+  ): Promise<{ ke3: Uint8Array }>;
+  registrationStart(
+    password: string,
+  ): Promise<{ request: Uint8Array; state: unknown }>;
+  registrationFinish(
+    password: string,
+    response: Uint8Array,
+    state: unknown,
+  ): Promise<{ record: Uint8Array }>;
+}
+
+export type OpaqueClientFactory = (
+  serverId: string,
+  clientId: string,
+) => OpaqueClientApi;
+
+/**
+ * Create an OPAQUE auth composable with injected crypto client.
+ *
+ * @param createClient - Factory that creates an OpaqueClientApi instance
+ * @param serverId - OPAQUE server identifier (default: "structured.id")
+ *
+ * @example
+ * ```ts
+ * import { OpaqueClient } from "@structured-id/opaque";
+ * import { createOpaqueAuth } from "@structured-id/ui-core/profile";
+ *
+ * const { login, register } = createOpaqueAuth(
+ *   (serverId, clientId) => new OpaqueClient({ serverId, clientId }),
+ * );
+ * ```
+ */
+export function createOpaqueAuth(
+  createClient: OpaqueClientFactory,
+  serverId = "structured.id",
+) {
+  /**
+   * Perform full OPAQUE login flow (2 round-trips via gRPC-web).
+   *
+   * 1. loginStart: send credentialRequest → receive credentialResponse + serverLoginState
+   * 2. loginFinish: send credentialFinalization → receive session tokens
+   */
+  async function login(
+    identifier: string,
+    password: string,
+    onStep?: (step: number) => void,
+  ): Promise<LoginResult> {
+    const opaque = createClient(serverId, identifier);
+
+    // Step 1: Generate credential request (client-side only, password never sent)
+    onStep?.(1);
+    const start = await opaque.loginStart(password);
+
+    // Step 2: Send credential request to server
+    onStep?.(2);
+    const startResp = await opaqueLoginStart(identifier, start.ke1);
+
+    // Step 3: Process server response, generate finalization (client-side crypto)
+    onStep?.(3);
+    const finish = await opaque.loginFinish(
+      password,
+      startResp.credentialResponse,
+      start.state,
+    );
+
+    // Step 4: Send finalization, receive session tokens
+    const finishResp = await opaqueLoginFinish(
+      identifier,
+      finish.ke3,
+      startResp.serverLoginState,
+    );
+
+    return {
+      sessionId: finishResp.sessionId,
+      accessToken: finishResp.accessToken,
+      expiresIn: Number(finishResp.expiresIn),
+    };
+  }
+
+  /**
+   * Perform full OPAQUE registration flow (2 round-trips via gRPC-web).
+   *
+   * 1. registrationStart: send registrationRequest → receive registrationResponse + serverSetup
+   * 2. registrationFinish: send registrationRecord → receive profileId + credentialId
+   */
+  async function register(
+    identifier: string,
+    password: string,
+  ): Promise<RegisterResult> {
+    const opaque = createClient(serverId, identifier);
+
+    // Step 1: Generate registration request
+    const start = await opaque.registrationStart(password);
+
+    const startResp = await opaqueRegistrationStart(
+      identifier,
+      start.request,
+    );
+
+    // Step 2: Process server response, generate registration record
+    const finish = await opaque.registrationFinish(
+      password,
+      startResp.registrationResponse,
+      start.state,
+    );
+
+    const finishResp = await opaqueRegistrationFinish(
+      identifier,
+      finish.record,
+      startResp.serverSetup,
+    );
+
+    return {
+      profileId: finishResp.profileId,
+      credentialId: finishResp.credentialId,
+    };
+  }
+
+  /**
+   * Compute OPAQUE registration record WITHOUT storing the credential.
+   *
+   * Used by password reset: the registration_record is passed to
+   * CompletePasswordReset RPC which stores the credential in the
+   * context of the reset session (replacing the old one).
+   *
+   * 1. registrationStart: send registrationRequest → receive registrationResponse
+   * 2. Client-side finish: compute registrationRecord (NOT sent to server yet)
+   */
+  async function computeRegistrationRecord(
+    identifier: string,
+    password: string,
+  ): Promise<Uint8Array> {
+    const opaque = createClient(serverId, identifier);
+
+    const start = await opaque.registrationStart(password);
+
+    const startResp = await opaqueRegistrationStart(
+      identifier,
+      start.request,
+    );
+
+    const finish = await opaque.registrationFinish(
+      password,
+      startResp.registrationResponse,
+      start.state,
+    );
+
+    return finish.record;
+  }
+
+  return { login, register, computeRegistrationRecord };
+}

package/src/profile/composables/useSecurityLevel.test.ts

@@ -0,0 +1,198 @@
+import { describe, it, expect } from "vitest";
+import { ref } from "vue";
+import {
+  useSecurityLevel,
+  SecurityLevel,
+  RecoverabilityLevel,
+} from "./useSecurityLevel";
+import {
+  CredentialType,
+  AuthenticatorAttachment,
+  PrincipalType,
+  type Credential,
+  type Principal,
+} from "../../index";
+import { PrincipalSubjectType } from "../../generated/sid/v1/identity/identity";
+
+// ── Helpers ──
+
+function makeCred(
+  type: CredentialType,
+  opts?: { attachment?: AuthenticatorAttachment; backupState?: boolean },
+): Credential {
+  const cred: Credential = {
+    id: "cred-1",
+    profileId: "",
+    type,
+    data: new Uint8Array(),
+    info: { oneofKind: undefined },
+  };
+  if (type === CredentialType.WEBAUTHN) {
+    cred.info = {
+      oneofKind: "webauthnInfo",
+      webauthnInfo: {
+        attachment: opts?.attachment ?? AuthenticatorAttachment.PLATFORM,
+        backupState: opts?.backupState ?? false,
+        backupEligible: false,
+        userVerified: true,
+        transports: [],
+        attestationFormat: "",
+      },
+    };
+  }
+  return cred;
+}
+
+function makePrincipal(type: PrincipalType, verified: boolean): Principal {
+  return {
+    id: "p-1",
+    type,
+    value: "test",
+    verified,
+    isPrimary: false,
+    subjectType: PrincipalSubjectType.PROFILE,
+    subjectId: "",
+  };
+}
+
+// ── Security Level ──
+
+describe("useSecurityLevel", () => {
+  it("MINIMAL with no credentials", () => {
+    const { securityLevel } = useSecurityLevel(ref([]), ref([]));
+    expect(securityLevel.value).toBe(SecurityLevel.MINIMAL);
+  });
+
+  it("MINIMAL with only password", () => {
+    const creds = ref([makeCred(CredentialType.OPAQUE)]);
+    const { securityLevel, factorCount } = useSecurityLevel(creds, ref([]));
+    expect(securityLevel.value).toBe(SecurityLevel.MINIMAL);
+    expect(factorCount.value).toBe(1);
+  });
+
+  it("BASIC with password + TOTP (2 factors, 2 categories)", () => {
+    const creds = ref([
+      makeCred(CredentialType.OPAQUE),
+      makeCred(CredentialType.TOTP),
+    ]);
+    const { securityLevel } = useSecurityLevel(creds, ref([]));
+    expect(securityLevel.value).toBe(SecurityLevel.STANDARD);
+  });
+
+  it("STRONG with 3 factors, 2 categories", () => {
+    const creds = ref([
+      makeCred(CredentialType.OPAQUE),
+      makeCred(CredentialType.TOTP),
+      makeCred(CredentialType.WEBAUTHN, {
+        attachment: AuthenticatorAttachment.PLATFORM,
+      }),
+    ]);
+    const { securityLevel } = useSecurityLevel(creds, ref([]));
+    expect(securityLevel.value).toBe(SecurityLevel.STRONG);
+  });
+
+  it("MAXIMUM with 3 factors, 3 categories, hardware key", () => {
+    const creds = ref([
+      makeCred(CredentialType.OPAQUE), // knowledge
+      makeCred(CredentialType.WEBAUTHN, {
+        attachment: AuthenticatorAttachment.PLATFORM,
+      }), // inherence
+      makeCred(CredentialType.WEBAUTHN, {
+        attachment: AuthenticatorAttachment.CROSS_PLATFORM,
+      }), // possession (hardware)
+    ]);
+    const { securityLevel } = useSecurityLevel(creds, ref([]));
+    expect(securityLevel.value).toBe(SecurityLevel.MAXIMUM);
+  });
+
+  it("recovery codes not counted as auth factor", () => {
+    const creds = ref([
+      makeCred(CredentialType.OPAQUE),
+      makeCred(CredentialType.RECOVERY),
+    ]);
+    const { factorCount } = useSecurityLevel(creds, ref([]));
+    expect(factorCount.value).toBe(1); // only password
+  });
+});
+
+// ── Recoverability ──
+
+describe("recoverability", () => {
+  it("NONE with no recovery methods", () => {
+    const { recoverabilityLevel } = useSecurityLevel(ref([]), ref([]));
+    expect(recoverabilityLevel.value).toBe(RecoverabilityLevel.NONE);
+  });
+
+  it("FRAGILE with only recovery codes", () => {
+    const creds = ref([makeCred(CredentialType.RECOVERY)]);
+    const { recoverabilityLevel } = useSecurityLevel(creds, ref([]));
+    expect(recoverabilityLevel.value).toBe(RecoverabilityLevel.FRAGILE);
+  });
+
+  it("STANDARD with recovery codes + verified email", () => {
+    const creds = ref([makeCred(CredentialType.RECOVERY)]);
+    const principals = ref([makePrincipal(PrincipalType.EMAIL, true)]);
+    const { recoverabilityLevel } = useSecurityLevel(creds, principals);
+    expect(recoverabilityLevel.value).toBe(RecoverabilityLevel.STANDARD);
+  });
+
+  it("ROBUST with codes + email + phone", () => {
+    const creds = ref([makeCred(CredentialType.RECOVERY)]);
+    const principals = ref([
+      makePrincipal(PrincipalType.EMAIL, true),
+      makePrincipal(PrincipalType.PHONE, true),
+    ]);
+    const { recoverabilityLevel } = useSecurityLevel(creds, principals);
+    expect(recoverabilityLevel.value).toBe(RecoverabilityLevel.ROBUST);
+  });
+
+  it("synced passkey counts as recovery method", () => {
+    const creds = ref([
+      makeCred(CredentialType.WEBAUTHN, {
+        attachment: AuthenticatorAttachment.PLATFORM,
+        backupState: true,
+      }),
+    ]);
+    const { recoveryMethods } = useSecurityLevel(creds, ref([]));
+    expect(recoveryMethods.value).toContain("synced_passkey");
+  });
+
+  it("unverified email not counted", () => {
+    const principals = ref([makePrincipal(PrincipalType.EMAIL, false)]);
+    const { recoveryMethods } = useSecurityLevel(ref([]), principals);
+    expect(recoveryMethods.value).not.toContain("recovery_email");
+  });
+});
+
+// ── Nudges ──
+
+describe("nudges", () => {
+  it("suggests recovery setup when no recovery codes", () => {
+    const creds = ref([makeCred(CredentialType.OPAQUE)]);
+    const { nudges } = useSecurityLevel(creds, ref([]));
+    expect(nudges.value.some((n) => n.id === "setup_recovery")).toBe(true);
+  });
+
+  it("suggests MFA when only password", () => {
+    const creds = ref([makeCred(CredentialType.OPAQUE)]);
+    const { nudges } = useSecurityLevel(creds, ref([]));
+    expect(nudges.value.some((n) => n.id === "setup_mfa")).toBe(true);
+  });
+
+  it("no MFA nudge when passkey exists", () => {
+    const creds = ref([
+      makeCred(CredentialType.OPAQUE),
+      makeCred(CredentialType.WEBAUTHN),
+    ]);
+    const { nudges } = useSecurityLevel(creds, ref([]));
+    expect(nudges.value.some((n) => n.id === "setup_mfa")).toBe(false);
+  });
+
+  it("nudges sorted by priority", () => {
+    const creds = ref([makeCred(CredentialType.OPAQUE)]);
+    const principals = ref([makePrincipal(PrincipalType.EMAIL, false)]);
+    const { nudges } = useSecurityLevel(creds, principals);
+    const priorities = nudges.value.map((n) => n.priority);
+    expect(priorities).toEqual([...priorities].sort((a, b) => a - b));
+  });
+});

package/src/profile/composables/useSecurityLevel.ts

@@ -0,0 +1,324 @@
+/**
+ * Security level and recoverability assessment composable.
+ *
+ * Pure computation — no API calls, no auth dependency.
+ * Analyzes credentials and principals to determine account security posture.
+ */
+import { computed, type Ref } from "vue";
+import {
+  type Credential,
+  type Principal,
+  CredentialType,
+  AuthenticatorAttachment,
+  PrincipalType,
+} from "../../index";
+
+// ── Security Level ──
+
+export enum SecurityLevel {
+  MINIMAL = 1,
+  BASIC = 2,
+  STANDARD = 3,
+  STRONG = 4,
+  MAXIMUM = 5,
+}
+
+const SECURITY_LEVEL_LABELS: Record<SecurityLevel, string> = {
+  [SecurityLevel.MINIMAL]: "Minimal",
+  [SecurityLevel.BASIC]: "Basic",
+  [SecurityLevel.STANDARD]: "Standard",
+  [SecurityLevel.STRONG]: "Strong",
+  [SecurityLevel.MAXIMUM]: "Maximum",
+};
+
+const SECURITY_LEVEL_COLORS: Record<SecurityLevel, string> = {
+  [SecurityLevel.MINIMAL]: "negative",
+  [SecurityLevel.BASIC]: "warning",
+  [SecurityLevel.STANDARD]: "info",
+  [SecurityLevel.STRONG]: "positive",
+  [SecurityLevel.MAXIMUM]: "positive",
+};
+
+// ── Recoverability Level ──
+
+export enum RecoverabilityLevel {
+  NONE = 0,
+  FRAGILE = 1,
+  STANDARD = 2,
+  ROBUST = 3,
+}
+
+const RECOVERABILITY_LABELS: Record<RecoverabilityLevel, string> = {
+  [RecoverabilityLevel.NONE]: "None",
+  [RecoverabilityLevel.FRAGILE]: "Fragile",
+  [RecoverabilityLevel.STANDARD]: "Standard",
+  [RecoverabilityLevel.ROBUST]: "Robust",
+};
+
+const RECOVERABILITY_COLORS: Record<RecoverabilityLevel, string> = {
+  [RecoverabilityLevel.NONE]: "negative",
+  [RecoverabilityLevel.FRAGILE]: "warning",
+  [RecoverabilityLevel.STANDARD]: "info",
+  [RecoverabilityLevel.ROBUST]: "positive",
+};
+
+// ── Factor Categories ──
+
+export type FactorCategory = "knowledge" | "possession" | "inherence";
+
+function getCategory(cred: Credential): FactorCategory | null {
+  switch (cred.type) {
+    case CredentialType.OPAQUE:
+    case CredentialType.LEGACY_HASH:
+      return "knowledge";
+    case CredentialType.TOTP:
+      return "possession";
+    case CredentialType.WEBAUTHN: {
+      if (cred.info.oneofKind === "webauthnInfo") {
+        return cred.info.webauthnInfo.attachment ===
+          AuthenticatorAttachment.PLATFORM
+          ? "inherence"
+          : "possession";
+      }
+      return "possession";
+    }
+    case CredentialType.RECOVERY:
+      return null; // recovery codes are not an auth factor
+    default:
+      return null;
+  }
+}
+
+function isHardwareKey(cred: Credential): boolean {
+  return (
+    cred.type === CredentialType.WEBAUTHN &&
+    cred.info.oneofKind === "webauthnInfo" &&
+    cred.info.webauthnInfo.attachment === AuthenticatorAttachment.CROSS_PLATFORM
+  );
+}
+
+// ── Action Nudge ──
+
+export interface ActionNudge {
+  id: string;
+  icon: string;
+  label: string;
+  description: string;
+  color: string;
+  priority: number;
+  to?: string;
+  action?: string;
+}
+
+// ── Composable ──
+
+export function useSecurityLevel(
+  credentials: Ref<Credential[]>,
+  identifiers: Ref<Principal[]>,
+) {
+  const authFactors = computed(() =>
+    credentials.value.filter((c) => c.type !== CredentialType.RECOVERY),
+  );
+
+  const factorCount = computed(() => authFactors.value.length);
+
+  const categories = computed(() => {
+    const cats = new Set<FactorCategory>();
+    for (const cred of authFactors.value) {
+      const cat = getCategory(cred);
+      if (cat) cats.add(cat);
+    }
+    return cats;
+  });
+
+  const hasHardwareKey = computed(() => authFactors.value.some(isHardwareKey));
+
+  const securityLevel = computed<SecurityLevel>(() => {
+    const count = factorCount.value;
+    const catCount = categories.value.size;
+
+    if (count >= 3 && catCount >= 3 && hasHardwareKey.value) {
+      return SecurityLevel.MAXIMUM;
+    }
+    if (count >= 3 && catCount >= 2) {
+      return SecurityLevel.STRONG;
+    }
+    if (count >= 2 && catCount >= 2) {
+      return SecurityLevel.STANDARD;
+    }
+    if (count >= 2) {
+      return SecurityLevel.BASIC;
+    }
+    return SecurityLevel.MINIMAL;
+  });
+
+  const securityLabel = computed(
+    () => SECURITY_LEVEL_LABELS[securityLevel.value],
+  );
+  const securityColor = computed(
+    () => SECURITY_LEVEL_COLORS[securityLevel.value],
+  );
+  const securityProgress = computed(() => securityLevel.value / 5);
+
+  // ── Recoverability ──
+
+  const recoveryMethods = computed(() => {
+    const methods: string[] = [];
+
+    if (credentials.value.some((c) => c.type === CredentialType.RECOVERY)) {
+      methods.push("recovery_codes");
+    }
+
+    if (
+      credentials.value.some(
+        (c) =>
+          c.type === CredentialType.WEBAUTHN &&
+          c.info.oneofKind === "webauthnInfo" &&
+          c.info.webauthnInfo.backupState,
+      )
+    ) {
+      methods.push("synced_passkey");
+    }
+
+    const emails = identifiers.value.filter(
+      (i) => i.type === PrincipalType.EMAIL && i.verified,
+    );
+    if (emails.length > 0) {
+      methods.push("recovery_email");
+    }
+
+    const phones = identifiers.value.filter(
+      (i) => i.type === PrincipalType.PHONE && i.verified,
+    );
+    if (phones.length > 0) {
+      methods.push("recovery_phone");
+    }
+
+    return methods;
+  });
+
+  const hasDeviceIndependent = computed(() =>
+    recoveryMethods.value.some((m) =>
+      ["recovery_codes", "recovery_email", "recovery_phone"].includes(m),
+    ),
+  );
+
+  const recoverabilityLevel = computed<RecoverabilityLevel>(() => {
+    const count = recoveryMethods.value.length;
+    if (count >= 3) return RecoverabilityLevel.ROBUST;
+    if (count >= 2 && hasDeviceIndependent.value)
+      return RecoverabilityLevel.STANDARD;
+    if (count >= 1) return RecoverabilityLevel.FRAGILE;
+    return RecoverabilityLevel.NONE;
+  });
+
+  const recoverabilityLabel = computed(
+    () => RECOVERABILITY_LABELS[recoverabilityLevel.value],
+  );
+  const recoverabilityColor = computed(
+    () => RECOVERABILITY_COLORS[recoverabilityLevel.value],
+  );
+  const recoverabilityProgress = computed(() => recoverabilityLevel.value / 3);
+
+  // ── Action Nudges ──
+
+  const nudges = computed<ActionNudge[]>(() => {
+    const items: ActionNudge[] = [];
+
+    const hasPasskey = credentials.value.some(
+      (c) => c.type === CredentialType.WEBAUTHN,
+    );
+    const hasTotp = credentials.value.some(
+      (c) => c.type === CredentialType.TOTP,
+    );
+    const hasRecovery = credentials.value.some(
+      (c) => c.type === CredentialType.RECOVERY,
+    );
+    const verifiedEmails = identifiers.value.filter(
+      (i) => i.type === PrincipalType.EMAIL && i.verified,
+    );
+    const unverifiedEmails = identifiers.value.filter(
+      (i) => i.type === PrincipalType.EMAIL && !i.verified,
+    );
+
+    if (!hasRecovery) {
+      items.push({
+        id: "setup_recovery",
+        icon: "sym_o_key",
+        label: "Set up recovery",
+        description:
+          "Generate recovery codes to regain access if you lose your credentials",
+        color: "negative",
+        priority: 1,
+        action: "generate_recovery",
+      });
+    }
+
+    if (!hasPasskey && !hasTotp) {
+      items.push({
+        id: "setup_mfa",
+        icon: "sym_o_shield",
+        label: "Enable multi-factor authentication",
+        description:
+          "Add a second factor to protect your account from unauthorized access",
+        color: "warning",
+        priority: 2,
+        to: "/account/security",
+      });
+    }
+
+    if (unverifiedEmails.length > 0) {
+      items.push({
+        id: "verify_email",
+        icon: "sym_o_mark_email_read",
+        label: "Verify your email",
+        description: "Confirm your email address for account recovery",
+        color: "warning",
+        priority: 3,
+        to: "/account/profile",
+      });
+    }
+
+    if (!hasPasskey) {
+      items.push({
+        id: "add_passkey",
+        icon: "sym_o_passkey",
+        label: "Add a passkey",
+        description:
+          "Passkeys provide phishing-resistant, passwordless sign-in",
+        color: "info",
+        priority: 4,
+        to: "/auth/webauthn-enrollment",
+      });
+    }
+
+    if (verifiedEmails.length < 2 && unverifiedEmails.length === 0) {
+      items.push({
+        id: "add_backup_email",
+        icon: "sym_o_alternate_email",
+        label: "Add a backup email",
+        description: "A secondary email helps with account recovery",
+        color: "grey",
+        priority: 5,
+        to: "/account/profile",
+      });
+    }
+
+    return items.sort((a, b) => a.priority - b.priority);
+  });
+
+  return {
+    securityLevel,
+    securityLabel,
+    securityColor,
+    securityProgress,
+    factorCount,
+    categories,
+    recoverabilityLevel,
+    recoverabilityLabel,
+    recoverabilityColor,
+    recoverabilityProgress,
+    recoveryMethods,
+    nudges,
+  };
+}