@sentropic/auth-ui 0.2.0

package/src/transport-fetch.ts

@@ -0,0 +1,170 @@
+import { createAuthUiError } from './errors.js';
+import type {
+  ApproveDevicePairingInput,
+  ApproveDevicePairingResult,
+  AuthUiTransport,
+  CreatePasskeyAuthenticationOptionsInput,
+  CreatePasskeyAuthenticationOptionsResult,
+  CreatePasskeyRegistrationOptionsInput,
+  CreatePasskeyRegistrationOptionsResult,
+  ListCredentialsResult,
+  RenameCredentialInput,
+  RequestEmailCodeInput,
+  RequestEmailCodeResult,
+  RevokeCredentialInput,
+  VerifyEmailCodeInput,
+  VerifyEmailCodeResult,
+  VerifyMagicLinkInput,
+  VerifyPasskeyAuthenticationInput,
+  VerifyPasskeyRegistrationInput,
+} from './transport-types.js';
+import type { AuthUiCredential, AuthUiResult, AuthUiSession } from './types.js';
+
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+
+export interface CreateDefaultFetchTransportOptions {
+  /**
+   * Base URL prefix mounted in front of the auth routes (e.g. "/auth", "/admin/auth").
+   * No trailing slash.
+   */
+  baseUrl: string;
+  fetch?: FetchLike;
+  /**
+   * Static headers merged into every request (e.g. tenant id, bearer token).
+   */
+  headers?: Record<string, string>;
+  /**
+   * Invoked when an authenticated request receives a 401 response, so hosts can
+   * clear their session state and redirect to login.
+   */
+  onUnauthorized?: () => void | Promise<void>;
+  /**
+   * Toggle `credentials: "include"` so the browser sends cookies. Default `true`.
+   */
+  withCredentials?: boolean;
+}
+
+const safeJson = async (response: Response): Promise<unknown> => {
+  const text = await response.text();
+  if (!text) {
+    return null;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+};
+
+const extractErrorMessage = (payload: unknown, fallback: string): string => {
+  if (payload && typeof payload === 'object') {
+    const record = payload as Record<string, unknown>;
+    if (typeof record.message === 'string' && record.message) {
+      return record.message;
+    }
+    if (typeof record.error === 'string' && record.error) {
+      return record.error;
+    }
+  }
+  return fallback;
+};
+
+export const createDefaultFetchTransport = (
+  options: CreateDefaultFetchTransportOptions,
+): AuthUiTransport => {
+  const baseUrl = options.baseUrl.replace(/\/$/, '');
+  const fetchImpl = options.fetch ?? (typeof fetch === 'function' ? fetch.bind(globalThis) : undefined);
+  const withCredentials = options.withCredentials ?? true;
+
+  if (!fetchImpl) {
+    throw createAuthUiError(
+      'invalid_input',
+      'No global fetch found; pass options.fetch when constructing the auth transport.',
+    );
+  }
+
+  const request = async <T>(
+    path: string,
+    init: { method: 'GET' | 'POST' | 'PUT' | 'DELETE'; body?: unknown; authenticated?: boolean },
+  ): Promise<AuthUiResult<T>> => {
+    const headers: Record<string, string> = { Accept: 'application/json', ...(options.headers ?? {}) };
+    let body: BodyInit | undefined;
+    if (init.body !== undefined) {
+      headers['Content-Type'] = 'application/json';
+      body = JSON.stringify(init.body);
+    }
+
+    let response: Response;
+    try {
+      response = await fetchImpl(`${baseUrl}${path}`, {
+        method: init.method,
+        headers,
+        body,
+        credentials: withCredentials ? 'include' : 'same-origin',
+      });
+    } catch (cause) {
+      return {
+        ok: false,
+        error: createAuthUiError('transport_error', 'Network request failed', { retryable: true, cause }),
+      };
+    }
+
+    const payload = await safeJson(response);
+
+    if (response.status === 401 && init.authenticated) {
+      void options.onUnauthorized?.();
+    }
+
+    if (!response.ok) {
+      const message = extractErrorMessage(payload, `Request failed with status ${response.status}`);
+      return {
+        ok: false,
+        error: createAuthUiError('transport_error', message, {
+          retryable: response.status >= 500,
+          cause: payload,
+        }),
+      };
+    }
+
+    return { ok: true, value: payload as T };
+  };
+
+  return {
+    requestEmailCode: (input: RequestEmailCodeInput) =>
+      request<RequestEmailCodeResult>('/email/verify-request', { method: 'POST', body: input }),
+    verifyEmailCode: (input: VerifyEmailCodeInput) =>
+      request<VerifyEmailCodeResult>('/email/verify-code', { method: 'POST', body: input }),
+    verifyMagicLink: (input: VerifyMagicLinkInput) =>
+      request<AuthUiSession>('/magic-link/verify', { method: 'POST', body: input }),
+    createPasskeyRegistrationOptions: (input: CreatePasskeyRegistrationOptionsInput) =>
+      request<CreatePasskeyRegistrationOptionsResult>('/register/options', { method: 'POST', body: input }),
+    verifyPasskeyRegistration: (input: VerifyPasskeyRegistrationInput) =>
+      request<AuthUiSession>('/register/verify', { method: 'POST', body: input }),
+    createPasskeyAuthenticationOptions: (input: CreatePasskeyAuthenticationOptionsInput) =>
+      request<CreatePasskeyAuthenticationOptionsResult>('/login/options', { method: 'POST', body: input }),
+    verifyPasskeyAuthentication: (input: VerifyPasskeyAuthenticationInput) =>
+      request<AuthUiSession>('/login/verify', { method: 'POST', body: input }),
+    refreshSession: () =>
+      request<AuthUiSession>('/session/refresh', { method: 'POST', authenticated: true }),
+    logout: () => request<void>('/session', { method: 'DELETE', authenticated: true }),
+    listCredentials: () =>
+      request<ListCredentialsResult>('/credentials', { method: 'GET', authenticated: true }),
+    renameCredential: (input: RenameCredentialInput) =>
+      request<AuthUiCredential>(`/credentials/${encodeURIComponent(input.credentialId)}`, {
+        method: 'PUT',
+        body: { deviceName: input.deviceName },
+        authenticated: true,
+      }),
+    revokeCredential: (input: RevokeCredentialInput) =>
+      request<void>(`/credentials/${encodeURIComponent(input.credentialId)}`, {
+        method: 'DELETE',
+        authenticated: true,
+      }),
+    approveDevicePairing: (input: ApproveDevicePairingInput) =>
+      request<ApproveDevicePairingResult>('/device/approve', {
+        method: 'POST',
+        body: { user_code: input.userCode, device_name: input.deviceName },
+        authenticated: true,
+      }),
+  };
+};

package/src/transport-types.ts

@@ -0,0 +1,105 @@
+import type {
+  AuthenticationResponseJSON,
+  PublicKeyCredentialCreationOptionsJSON,
+  PublicKeyCredentialRequestOptionsJSON,
+  RegistrationResponseJSON,
+} from '@simplewebauthn/browser';
+
+import type { AuthUiCredential, AuthUiResult, AuthUiSession } from './types.js';
+
+export interface RequestEmailCodeInput {
+  email: string;
+}
+
+export interface RequestEmailCodeResult {
+  delivery: 'email' | 'magic_link' | string;
+  expiresAt?: string;
+}
+
+export interface VerifyEmailCodeInput {
+  email: string;
+  code: string;
+}
+
+export interface VerifyEmailCodeResult {
+  verificationToken: string;
+}
+
+export interface VerifyMagicLinkInput {
+  token: string;
+}
+
+export interface CreatePasskeyRegistrationOptionsInput {
+  email: string;
+  verificationToken: string;
+  deviceName?: string;
+}
+
+export interface CreatePasskeyRegistrationOptionsResult {
+  userId: string;
+  options: PublicKeyCredentialCreationOptionsJSON;
+}
+
+export interface VerifyPasskeyRegistrationInput {
+  email: string;
+  verificationToken: string;
+  userId: string;
+  credential: RegistrationResponseJSON;
+  deviceName?: string;
+}
+
+export interface CreatePasskeyAuthenticationOptionsInput {
+  email?: string;
+}
+
+export interface CreatePasskeyAuthenticationOptionsResult {
+  options: PublicKeyCredentialRequestOptionsJSON;
+}
+
+export interface VerifyPasskeyAuthenticationInput {
+  credential: AuthenticationResponseJSON;
+}
+
+export interface RenameCredentialInput {
+  credentialId: string;
+  deviceName: string;
+}
+
+export interface RevokeCredentialInput {
+  credentialId: string;
+}
+
+export interface ListCredentialsResult {
+  credentials: AuthUiCredential[];
+}
+
+export interface ApproveDevicePairingInput {
+  userCode: string;
+  deviceName?: string;
+}
+
+export interface ApproveDevicePairingResult {
+  deviceName?: string;
+}
+
+export interface AuthUiTransport {
+  requestEmailCode(input: RequestEmailCodeInput): Promise<AuthUiResult<RequestEmailCodeResult>>;
+  verifyEmailCode(input: VerifyEmailCodeInput): Promise<AuthUiResult<VerifyEmailCodeResult>>;
+  verifyMagicLink(input: VerifyMagicLinkInput): Promise<AuthUiResult<AuthUiSession>>;
+  createPasskeyRegistrationOptions(
+    input: CreatePasskeyRegistrationOptionsInput,
+  ): Promise<AuthUiResult<CreatePasskeyRegistrationOptionsResult>>;
+  verifyPasskeyRegistration(input: VerifyPasskeyRegistrationInput): Promise<AuthUiResult<AuthUiSession>>;
+  createPasskeyAuthenticationOptions(
+    input: CreatePasskeyAuthenticationOptionsInput,
+  ): Promise<AuthUiResult<CreatePasskeyAuthenticationOptionsResult>>;
+  verifyPasskeyAuthentication(input: VerifyPasskeyAuthenticationInput): Promise<AuthUiResult<AuthUiSession>>;
+  refreshSession(): Promise<AuthUiResult<AuthUiSession>>;
+  logout(): Promise<AuthUiResult<void>>;
+  listCredentials(): Promise<AuthUiResult<ListCredentialsResult>>;
+  renameCredential(input: RenameCredentialInput): Promise<AuthUiResult<AuthUiCredential>>;
+  revokeCredential(input: RevokeCredentialInput): Promise<AuthUiResult<void>>;
+  approveDevicePairing(
+    input: ApproveDevicePairingInput,
+  ): Promise<AuthUiResult<ApproveDevicePairingResult>>;
+}

package/src/transport.ts

@@ -0,0 +1,33 @@
+import { createAuthUiError } from './errors.js';
+import type { AuthUiTransport } from './transport-types.js';
+
+export const assertAuthUiTransport = (candidate: unknown): AuthUiTransport => {
+  const requiredMethods: Array<keyof AuthUiTransport> = [
+    'requestEmailCode',
+    'verifyEmailCode',
+    'verifyMagicLink',
+    'createPasskeyRegistrationOptions',
+    'verifyPasskeyRegistration',
+    'createPasskeyAuthenticationOptions',
+    'verifyPasskeyAuthentication',
+    'refreshSession',
+    'logout',
+    'listCredentials',
+    'renameCredential',
+    'revokeCredential',
+    'approveDevicePairing',
+  ];
+
+  if (!candidate || typeof candidate !== 'object') {
+    throw createAuthUiError('invalid_input', 'Auth UI transport must be an object');
+  }
+
+  const record = candidate as Record<string, unknown>;
+  for (const method of requiredMethods) {
+    if (typeof record[method] !== 'function') {
+      throw createAuthUiError('invalid_input', `Auth UI transport is missing method ${method}`);
+    }
+  }
+
+  return candidate as AuthUiTransport;
+};

package/src/types.ts

@@ -0,0 +1,153 @@
+export type AuthUiErrorCode =
+  | 'invalid_input'
+  | 'transport_error'
+  | 'email_code_invalid'
+  | 'magic_link_invalid'
+  | 'passkey_cancelled'
+  | 'passkey_already_registered'
+  | 'passkey_no_matching_authenticator'
+  | 'passkey_not_supported'
+  | 'passkey_registration_failed'
+  | 'passkey_authentication_failed'
+  | 'credential_not_found'
+  | 'unknown';
+
+export interface AuthUiError extends Error {
+  readonly name: 'AuthUiError';
+  readonly code: AuthUiErrorCode;
+  readonly retryable: boolean;
+  readonly cause?: unknown;
+}
+
+export type AuthUiResult<T> =
+  | { ok: true; value: T }
+  | { ok: false; error: AuthUiError };
+
+export interface AuthUiUser {
+  id: string;
+  email: string;
+  displayName?: string | null;
+  role?: string | null;
+}
+
+export interface AuthUiSession {
+  user: AuthUiUser;
+  sessionToken?: string;
+  refreshToken?: string;
+  expiresAt?: string;
+}
+
+export interface AuthUiCredential {
+  id: string;
+  credentialId: string;
+  deviceName: string;
+  uv: boolean;
+  createdAt: string;
+  lastUsedAt: string | null;
+}
+
+export interface AuthUiNavigation {
+  navigate(to: string): void | Promise<void>;
+  buildLoginHref?(returnUrl?: string): string;
+  buildRegisterHref?(returnUrl?: string): string;
+  buildDevicesHref?(): string;
+}
+
+export interface AuthUiSessionCallbacks {
+  onSession?(session: AuthUiSession): void | Promise<void>;
+  onLogout?(): void | Promise<void>;
+  onError?(error: AuthUiError): void | Promise<void>;
+}
+
+export interface AuthUiBranding {
+  productName?: string;
+  logoUrl?: string;
+  logoAlt?: string;
+  primaryColor?: string;
+  accentColor?: string;
+}
+
+export interface AuthUiLabels {
+  loading: string;
+  save: string;
+  cancel: string;
+  emailPlaceholder: string;
+  webauthnRegisterNotice: string;
+  verifyInProgress: string;
+  redirectingDashboard: string;
+  registerDeviceNow: string;
+  loginTitle: string;
+  loginSupportedHint: string;
+  loginUnavailable: string;
+  loginUnsupportedBrowser: string;
+  loginButton: string;
+  loginButtonLoading: string;
+  loginLostDevice: string;
+  loginLostDeviceTitle: string;
+  loginNoAccount: string;
+  loginRegisterNewDevice: string;
+  loginBackToLogin: string;
+  registerTitle: string;
+  registerSubtitle: string;
+  registerUnsupportedBrowserTitle: string;
+  registerUnsupportedBrowser: string;
+  registerEmailLabel: string;
+  registerGetCode: string;
+  registerSendingCode: string;
+  registerAlreadyHaveAccount: string;
+  registerCodeLabel: string;
+  registerCodeHelp: string;
+  registerVerifyCode: string;
+  registerVerifyingCode: string;
+  registerChangeEmail: string;
+  registerCodeVerifiedTitle: string;
+  registerPasskeyButton: string;
+  registerRegistering: string;
+  registerSuccessTitle: string;
+  registerSuccessCodeSent: string;
+  registerSuccessRedirecting: string;
+  registerErrorInvalidEmail: string;
+  registerErrorSendCode: string;
+  magicLinkTitle: string;
+  magicLinkVerifying: string;
+  magicLinkSuccess: string;
+  magicLinkSuccessTitle: string;
+  magicLinkErrorTitle: string;
+  magicLinkBackToLogin: string;
+  magicLinkErrorMissingToken: string;
+  magicLinkErrorVerifyFailed: string;
+  devicesTitle: string;
+  devicesSubtitle: string;
+  devicesEmpty: string;
+  devicesRegister: string;
+  devicesAddNew: string;
+  devicesRename: string;
+  devicesRevoke: string;
+  devicesUvEnabled: string;
+  devicesAddedOn: string;
+  devicesLastUsed: string;
+  devicesConfirmRevoke: string;
+  devicesErrorLoad: string;
+  devicesErrorUpdate: string;
+  devicesErrorRevoke: string;
+  devicePairTitle: string;
+  devicePairSubtitle: string;
+  devicePairCodeLabel: string;
+  devicePairCodePlaceholder: string;
+  devicePairDeviceNameLabel: string;
+  devicePairDeviceNamePlaceholder: string;
+  devicePairConfirm: string;
+  devicePairConfirming: string;
+  devicePairSuccess: string;
+  devicePairBack: string;
+  devicePairErrorCodeRequired: string;
+  devicePairErrorNotFound: string;
+  devicePairErrorGeneric: string;
+  passkeyNotSupported: string;
+  passkeyCancelled: string;
+  passkeyAlreadyRegistered: string;
+  passkeyNoMatchingAuthenticator: string;
+  passkeyAuthenticatorNotSupported: string;
+  passkeyRegistrationCancelled: string;
+  passkeyAuthenticationCancelled: string;
+}

package/src/webauthn.ts

@@ -0,0 +1,133 @@
+import { startAuthentication as defaultStartAuthentication, startRegistration as defaultStartRegistration } from '@simplewebauthn/browser';
+import type {
+  AuthenticationResponseJSON,
+  PublicKeyCredentialCreationOptionsJSON,
+  PublicKeyCredentialRequestOptionsJSON,
+  RegistrationResponseJSON,
+} from '@simplewebauthn/browser';
+
+import { createAuthUiError, createDefaultAuthUiLabels, type AuthUiError, type AuthUiLabels } from './contracts.js';
+
+export interface AuthUiWebAuthnBrowser {
+  PublicKeyCredential?: {
+    new (...args: never[]): unknown;
+    isUserVerifyingPlatformAuthenticatorAvailable?: () => Promise<boolean>;
+  };
+}
+
+export interface StartPasskeyRegistrationOptions {
+  browser?: AuthUiWebAuthnBrowser;
+  startRegistration?: (input: { optionsJSON: PublicKeyCredentialCreationOptionsJSON }) => Promise<RegistrationResponseJSON>;
+}
+
+export interface StartPasskeyAuthenticationOptions {
+  browser?: AuthUiWebAuthnBrowser;
+  startAuthentication?: (input: { optionsJSON: PublicKeyCredentialRequestOptionsJSON }) => Promise<AuthenticationResponseJSON>;
+}
+
+const getDefaultBrowser = (): AuthUiWebAuthnBrowser | undefined =>
+  typeof window === 'undefined' ? undefined : (window as unknown as AuthUiWebAuthnBrowser);
+
+export const isWebAuthnSupported = (browser: AuthUiWebAuthnBrowser | undefined = getDefaultBrowser()): boolean =>
+  typeof browser?.PublicKeyCredential === 'function';
+
+export const isPlatformAuthenticatorAvailable = async (
+  browser: AuthUiWebAuthnBrowser | undefined = getDefaultBrowser(),
+): Promise<boolean> => {
+  if (!isWebAuthnSupported(browser)) {
+    return false;
+  }
+
+  try {
+    return Boolean(await browser?.PublicKeyCredential?.isUserVerifyingPlatformAuthenticatorAvailable?.());
+  } catch {
+    return false;
+  }
+};
+
+export const startPasskeyRegistration = async (
+  options: PublicKeyCredentialCreationOptionsJSON,
+  deps: StartPasskeyRegistrationOptions = {},
+): Promise<RegistrationResponseJSON> => {
+  if (!isWebAuthnSupported(deps.browser)) {
+    throw createAuthUiError('passkey_not_supported', 'WebAuthn is not supported in this browser');
+  }
+
+  try {
+    return await (deps.startRegistration ?? defaultStartRegistration)({ optionsJSON: options });
+  } catch (error) {
+    throw mapWebAuthnError(error, 'registration');
+  }
+};
+
+export const startPasskeyAuthentication = async (
+  options: PublicKeyCredentialRequestOptionsJSON,
+  deps: StartPasskeyAuthenticationOptions = {},
+): Promise<AuthenticationResponseJSON> => {
+  if (!isWebAuthnSupported(deps.browser)) {
+    throw createAuthUiError('passkey_not_supported', 'WebAuthn is not supported in this browser');
+  }
+
+  try {
+    return await (deps.startAuthentication ?? defaultStartAuthentication)({ optionsJSON: options });
+  } catch (error) {
+    throw mapWebAuthnError(error, 'authentication');
+  }
+};
+
+export const getWebAuthnErrorMessage = (
+  error: unknown,
+  labels: Partial<AuthUiLabels> = createDefaultAuthUiLabels(),
+): string => {
+  if (typeof error === 'string') {
+    return error;
+  }
+
+  const code = (error as Partial<AuthUiError> | undefined)?.code;
+  const message = (error as { message?: string } | undefined)?.message ?? 'Unknown error';
+
+  switch (code) {
+    case 'passkey_cancelled':
+      return labels.passkeyCancelled ?? message;
+    case 'passkey_already_registered':
+      return labels.passkeyAlreadyRegistered ?? message;
+    case 'passkey_no_matching_authenticator':
+      return labels.passkeyNoMatchingAuthenticator ?? message;
+    case 'passkey_not_supported':
+      return labels.passkeyNotSupported ?? message;
+    default:
+      return message;
+  }
+};
+
+const mapWebAuthnError = (error: unknown, ceremony: 'registration' | 'authentication'): AuthUiError => {
+  const name = (error as { name?: string } | undefined)?.name;
+  const message = (error as { message?: string } | undefined)?.message ?? 'Unknown error';
+
+  if (name === 'NotAllowedError') {
+    return createAuthUiError(
+      'passkey_cancelled',
+      ceremony === 'registration' ? 'Registration cancelled by user' : 'Authentication cancelled by user',
+      { retryable: true, cause: error },
+    );
+  }
+
+  if (name === 'InvalidStateError') {
+    const code = ceremony === 'registration' ? 'passkey_already_registered' : 'passkey_no_matching_authenticator';
+    const fallback = ceremony === 'registration' ? 'This authenticator is already registered' : 'No matching authenticator found';
+    return createAuthUiError(code, fallback, { retryable: ceremony !== 'registration', cause: error });
+  }
+
+  if (name === 'NotSupportedError') {
+    return createAuthUiError('passkey_not_supported', 'This authenticator is not supported', {
+      retryable: false,
+      cause: error,
+    });
+  }
+
+  return createAuthUiError(
+    ceremony === 'registration' ? 'passkey_registration_failed' : 'passkey_authentication_failed',
+    `${ceremony === 'registration' ? 'Registration' : 'Authentication'} failed: ${message}`,
+    { retryable: true, cause: error },
+  );
+};