@seamless-auth/react 0.0.10 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# @seamless-auth/react
+
+## 0.2.0
+
+### Minor Changes
+
+- 24a17b8: Release the current React SDK improvements as the first Changesets-managed package version.
+
+  This release includes the public headless client and React hooks for custom auth UIs, expanded provider helpers for OAuth and step-up flows, scoped role utilities, OTP and passkey flow polish, and the reviewed release PR workflow for future package publishing.
+
+## 0.1.1
+
+### Patch Changes
+
+- Last published version before Changesets-managed release PRs.

package/README.md

@@ -1,69 +1,87 @@
-# Seamless Auth React
-
 # @seamless-auth/react
 
 [![npm version](https://img.shields.io/npm/v/@seamless-auth/react.svg?label=%40seamless-auth%2Freact)](https://www.npmjs.com/package/@seamless-auth/react)
+[![CI](https://github.com/fells-code/seamless-auth-react/actions/workflows/ci.yml/badge.svg)](https://github.com/fells-code/seamless-auth-react/actions/workflows/ci.yml)
+[![Release](https://github.com/fells-code/seamless-auth-react/actions/workflows/release.yml/badge.svg)](https://github.com/fells-code/seamless-auth-react/actions/workflows/release.yml)
 [![coverage](https://img.shields.io/codecov/c/github/fells-code/seamless-auth-react)](https://app.codecov.io/gh/fells-code/seamless-auth-react)
 [![license](https://img.shields.io/github/license/fells-code/seamless-auth-react)](./LICENSE)
 
-A drop-in authentication provider for React applications, designed to handle login, multi-factor authentication, passkeys, and user session validation using your own backend.
-
-## Features
+`@seamless-auth/react` is a React SDK for Seamless Auth. It gives you a provider for auth state, a headless client and hooks for custom auth UIs, and optional prebuilt auth routes when you want a faster drop-in flow.
 
-- Provides `AuthProvider` context
-- Includes `useAuth()` hook for access to auth state and actions
-- Ships with pre-built login, MFA, and passkey routes
-- Lets consumer apps handle routing via `react-router-dom`
-- Supports automatic session validation on load
+## What It Exports
 
----
+- `AuthProvider`
+- `AuthRoutes`
+- `useAuth()`
+- `createSeamlessAuthClient()`
+- `useAuthClient()`
+- `usePasskeySupport()`
+- `hasScopedRole()` and `roleGrantsAccess()`
+- types including `AuthContextType`, `Credential`, `User`, `OAuthProvider`, `StepUpStatus`, and the headless client input/result types
 
 ## Installation
 
 ```bash
-npm install seamless-auth-react
+npm install @seamless-auth/react
 ```
 
----
+## Releases
+
+Published versions are listed in [CHANGELOG.md](./CHANGELOG.md) and GitHub Releases. Releases are
+managed with Changesets: adopter-facing changes include a changeset, the `Release` workflow opens a
+version PR for review, and merging that PR publishes the npm package with provenance from GitHub
+Actions. See [RELEASES.md](./RELEASES.md) for maintainer release details.
+
+## Choose Your Integration Style
+
+You can use this package in three ways:
 
-## Usage
+1. `AuthProvider` + `useAuth()` for auth state and core auth actions
+2. `createSeamlessAuthClient()` or `useAuthClient()` to build fully custom login and registration screens
+3. `AuthRoutes` when you want the built-in login, OTP, magic-link, and passkey screens
 
-### 1. Wrap your app with `AuthProvider`
+Most apps will use `AuthProvider` either way.
+
+## Quick Start
+
+### Wrap your app with `AuthProvider`
 
 ```tsx
-import { AuthProvider } from 'seamless-auth-react';
+import { AuthProvider } from '@seamless-auth/react';
 import { BrowserRouter } from 'react-router-dom';
 
 <BrowserRouter>
-  <AuthProvider apiHost="https://your.api/">
+  <AuthProvider apiHost="https://your.api">
     <AppRoutes />
   </AuthProvider>
 </BrowserRouter>;
 ```
 
-### 2. Use `useAuth()` to access auth state
+### Read auth state with `useAuth()`
 
 ```tsx
-import { useAuth } from 'seamless-auth-react';
+import { useAuth } from '@seamless-auth/react';
+
+function Dashboard() {
+  const { user, logout, refreshSession } = useAuth();
 
-const Dashboard = () => {
-  const { user, logout } = useAuth();
   return (
     <div>
-      Welcome, {user?.email}
-      <button onClick={logout}>Logout</button>
+      <p>Welcome, {user?.email}</p>
+      <button onClick={() => void refreshSession()}>Refresh session</button>
+      <button onClick={() => void logout()}>Logout</button>
     </div>
   );
-};
+}
 ```
 
-### 3. Use `<AuthRoutes />` for handling login/mfa/passkey screens
+### Use built-in auth routes with `AuthRoutes`
 
 ```tsx
-import { Routes, Route } from 'react-router-dom';
-import { useAuth, AuthRoutes } from 'seamless-auth-react';
+import { AuthRoutes, useAuth } from '@seamless-auth/react';
+import { Route, Routes } from 'react-router-dom';
 
-const AppRoutes = () => {
+function AppRoutes() {
   const { isAuthenticated } = useAuth();
 
   return (
@@ -75,59 +93,409 @@ const AppRoutes = () => {
       )}
     </Routes>
   );
-};
+}
 ```
 
-> Note: You are responsible for handling route protection and redirects based on `isAuthenticated`.
-
----
+You are still responsible for your app’s route protection and redirects.
 
-## AuthContext API
+## `useAuth()` API
 
-### `useAuth()` returns:
+`useAuth()` returns the current auth state plus the provider-backed helpers:
 
 ```ts
 {
-  user: { email: string, roles?: string[] } | null;
+  user: User | null;
+  credentials: Credential[];
+  stepUpStatus: StepUpStatus | null;
   isAuthenticated: boolean;
+  loading: boolean;
+  apiHost: string;
+  hasSignedInBefore: boolean;
+  markSignedIn(): void;
+  hasRole(role: string): boolean | undefined;
+  hasScopedRole(role: string | string[]): boolean | undefined;
+  listOAuthProviders(): Promise<OAuthProvidersResult>;
+  startOAuthLogin(input: StartOAuthLoginInput): Promise<StartOAuthLoginResult>;
+  finishOAuthLogin(input: FinishOAuthLoginInput): Promise<void>;
+  refreshSession(): Promise<void>;
+  refreshStepUpStatus(): Promise<StepUpStatus | null>;
+  verifyStepUpWithPasskey(): Promise<StepUpVerificationResult>;
+  verifyStepUpWithPasskeyPrf(input: PasskeyPrfInput): Promise<StepUpWithPasskeyPrfResult>;
   logout(): Promise<void>;
+  logoutAllSessions(): Promise<void>;
   deleteUser(): Promise<void>;
-  hasRole(role: string): boolean | undefined;
+  login(identifier: string, passkeyAvailable: boolean): Promise<Response>;
+  handlePasskeyLogin(): Promise<boolean>;
+  updateCredential(credential: Credential): Promise<Credential>;
+  deleteCredential(credentialId: string): Promise<void>;
 }
 ```
 
----
+Use `refreshSession()` after completing a custom auth flow that should update provider state.
+
+### `hasSignedInBefore`
+
+`hasSignedInBefore` is a small convenience flag backed by `localStorage`. The provider reads the `seamlessauth_seen` key on load and sets the flag to `true` after `markSignedIn()` runs.
+
+This is mainly useful for login UIs that want to branch between first-time and returning-user behavior. For example, the built-in `Login` view uses it to default returning users to sign-in mode instead of registration.
+
+```tsx
+import { useAuth } from '@seamless-auth/react';
+
+function SignInHint() {
+  const { hasSignedInBefore } = useAuth();
+
+  return hasSignedInBefore ? (
+    <p>Welcome back. Sign in with your email, phone, or passkey.</p>
+  ) : (
+    <p>New here? Start by creating your account.</p>
+  );
+}
+```
+
+If you are building a fully custom flow, call `markSignedIn()` after a successful sign-in or registration step once you want future visits treated as returning-user sessions.
+
+```tsx
+const { markSignedIn, refreshSession } = useAuth();
+
+async function completeLogin() {
+  const response = await authClient.login({
+    identifier: 'user@example.com',
+    passkeyAvailable: true,
+  });
+
+  if (response.ok) {
+    markSignedIn();
+    await refreshSession();
+  }
+}
+```
+
+To disable this auto-detection entirely, pass `autoDetectPreviousSignin={false}` to `AuthProvider`.
+
+### Scoped roles
+
+`hasRole(role)` remains an exact role check. Use `hasScopedRole(role)` for colon-separated scoped
+roles such as `admin:read` and `admin:write`.
 
-## Auth Routes Included
+```tsx
+const { hasRole, hasScopedRole } = useAuth();
+
+hasRole('admin'); // exact legacy role check
+hasScopedRole('admin:read'); // true for admin, admin:read, or admin:write
+hasScopedRole('admin:write'); // true for admin or admin:write
+```
+
+The package also exports standalone `hasScopedRole(roles, required)` and `roleGrantsAccess(...)`
+helpers for code that is not inside `AuthProvider`.
+
+### Step-up authentication
+
+Use step-up authentication before sensitive actions that should require a fresh user verification, such as deleting an account, changing MFA settings, or viewing recovery material.
+
+```tsx
+import { useAuth } from '@seamless-auth/react';
+
+function DeleteAccountButton() {
+  const { refreshStepUpStatus, verifyStepUpWithPasskey } = useAuth();
+
+  async function handleDeleteAccount() {
+    const status = await refreshStepUpStatus();
+    const fresh = status?.fresh ? true : (await verifyStepUpWithPasskey()).success;
+
+    if (!fresh) {
+      return;
+    }
+
+    await deleteAccount();
+  }
+
+  return <button onClick={() => void handleDeleteAccount()}>Delete account</button>;
+}
+```
+
+The current step-up backend supports WebAuthn/passkeys. `refreshStepUpStatus()` calls `/step-up/status`, and `verifyStepUpWithPasskey()` performs the `/step-up/webauthn/start` and `/step-up/webauthn/finish` challenge flow.
+
+### WebAuthn PRF
+
+WebAuthn PRF lets a compatible passkey and browser derive local key material during a WebAuthn assertion. Seamless Auth verifies the passkey assertion on the server, while the React SDK returns the PRF output only to the browser caller. PRF output is stripped before `/webAuthn/login/finish` and `/step-up/webauthn/finish`, and should never be logged, stored, or sent to your API.
+
+Browser and authenticator support is not universal. Call `isPasskeyPrfSupported()` before offering PRF-required flows, and keep a fallback for passkeys that authenticate successfully without returning PRF output.
+
+Treat PRF salts as sensitive in client logs. PRF output is browser-local key material; keep it in
+memory only as long as your application needs it and do not send it to Seamless Auth or your own API.
+
+```ts
+import { createSeamlessAuthClient } from '@seamless-auth/react';
+
+const authClient = createSeamlessAuthClient({
+  apiHost: 'https://your.api',
+});
+
+const prfSupported = await authClient.isPasskeyPrfSupported();
+
+if (prfSupported) {
+  await authClient.registerPasskey({
+    metadata: {
+      friendlyName: 'My laptop',
+      platform: 'macOS',
+      browser: 'Chrome',
+      deviceInfo: navigator.userAgent,
+    },
+    requirePrf: true,
+  });
+}
+```
+
+For local key unwrap flows such as Seamless Secrets, use PRF during step-up and consume the returned bytes in browser memory:
+
+```ts
+const result = await authClient.verifyStepUpWithPasskeyPrf({
+  salt: vaultSaltBase64url,
+  credentialId,
+});
+
+if (!result.success || !result.prf) {
+  throw new Error('PRF step-up failed');
+}
+
+const vaultUnlockMaterial: { credentialId: string; output: Uint8Array } = {
+  credentialId: result.credentialId!,
+  output: result.prf.output,
+};
+```
+
+The salt may be an `ArrayBuffer`, `ArrayBufferView`, or base64url string. Authentication proves identity and user presence; the PRF output is local key material for your application to use without sending it to Seamless Auth.
+
+### OAuth Login
+
+OAuth lets your app offer external identity providers such as Google, GitHub, Facebook, or custom
+OIDC-style providers configured on the Seamless Auth API. The React SDK does not receive provider
+access tokens. It only starts the provider redirect and completes the callback so Seamless Auth can
+issue the normal access/refresh session.
+
+Use `listOAuthProviders()` when you want to render enabled providers dynamically:
+
+```tsx
+import { useEffect, useState } from 'react';
+import { useAuth } from '@seamless-auth/react';
+import type { OAuthProvider } from '@seamless-auth/react';
+
+function OAuthButtons() {
+  const { listOAuthProviders, startOAuthLogin } = useAuth();
+  const [providers, setProviders] = useState<OAuthProvider[]>([]);
+
+  useEffect(() => {
+    void listOAuthProviders().then(result => setProviders(result.providers));
+  }, [listOAuthProviders]);
+
+  async function signIn(providerId: string) {
+    const result = await startOAuthLogin({
+      providerId,
+      redirectUri: `${window.location.origin}/oauth/callback`,
+      returnTo: `${window.location.origin}/dashboard`,
+    });
+
+    window.location.assign(result.authorizationUrl);
+  }
+
+  return (
+    <div>
+      {providers.map(provider => (
+        <button key={provider.id} onClick={() => void signIn(provider.id)}>
+          Continue with {provider.name}
+        </button>
+      ))}
+    </div>
+  );
+}
+```
+
+Create a callback route that reads the provider query params and asks Seamless Auth to complete the
+login:
+
+```tsx
+import { useEffect } from 'react';
+import { useAuth } from '@seamless-auth/react';
+
+function OAuthCallback() {
+  const { finishOAuthLogin } = useAuth();
+
+  useEffect(() => {
+    const params = new URLSearchParams(window.location.search);
+    const providerId = 'google';
+    const code = params.get('code');
+    const state = params.get('state');
+
+    if (!code || !state) {
+      return;
+    }
+
+    void finishOAuthLogin({ providerId, code, state }).then(() => {
+      window.location.assign('/dashboard');
+    });
+  }, [finishOAuthLogin]);
+
+  return <p>Finishing sign-in...</p>;
+}
+```
+
+For fully custom UI without `useAuth()`, call the headless client directly:
+
+```ts
+const providers = await authClient.listOAuthProviders();
+const started = await authClient.startOAuthLogin({
+  providerId: providers.providers[0].id,
+  redirectUri: `${window.location.origin}/oauth/callback`,
+});
+
+window.location.assign(started.authorizationUrl);
+```
+
+OAuth must be enabled on the Seamless Auth API with `LOGIN_METHODS` including `oauth` and at least
+one configured `oauth_providers` entry. Provider client secrets live on the server and are referenced
+by environment variable name; they are never passed through this SDK.
+
+For production providers, configure exact `redirectUris` on the Seamless Auth API. The SDK should
+send the callback URL it expects to receive, but redirect allowlisting, signed state expiry, OIDC
+nonce handling, email verification policy, and account-linking policy are enforced by the API.
+
+The built-in views avoid logging OTPs, magic-link tokens, bootstrap tokens, PRF salts, or raw
+exception payloads that may contain sensitive request URLs.
+
+## Headless Client
+
+For custom auth UIs, use the exported client directly:
+
+```ts
+import { createSeamlessAuthClient } from '@seamless-auth/react';
+
+const authClient = createSeamlessAuthClient({
+  apiHost: 'https://your.api',
+});
+
+const response = await authClient.login({
+  identifier: 'user@example.com',
+  passkeyAvailable: true,
+});
+
+if (response.ok) {
+  // Continue your custom flow
+}
+```
+
+The headless client exposes helpers for:
+
+- current-user/session lookup
+- login and passkey login
+- registration
+- phone OTP and email OTP
+- magic-link request, verify, and polling
+- OAuth provider listing, start, and callback completion
+- passkey registration
+- step-up status and passkey verification
+- logout and delete-user
+- credential update and deletion
+
+Client methods return raw `Response` objects except for the passkey convenience helpers:
+
+- `loginWithPasskey(options?: PasskeyLoginOptions): Promise<PasskeyLoginWithPrfResult>`
+- `registerPasskey(metadata | { metadata, requestPrf?, requirePrf? }): Promise<PasskeyRegistrationResult>`
+- `isPasskeyPrfSupported(): Promise<boolean>`
+- `verifyStepUpWithPasskey(): Promise<StepUpVerificationResult>`
+- `verifyStepUpWithPasskeyPrf(input): Promise<StepUpWithPasskeyPrfResult>`
+- `listOAuthProviders(): Promise<OAuthProvidersResult>`
+- `startOAuthLogin(input): Promise<StartOAuthLoginResult>`
+- `finishOAuthLogin(input): Promise<Response>`
+
+## React Hooks For Custom UI
+
+If you want custom React screens but do not want to manually recreate the client, use the exported hooks:
+
+```tsx
+import { useAuth, useAuthClient, usePasskeySupport } from '@seamless-auth/react';
+
+function CustomLogin() {
+  const { refreshSession } = useAuth();
+  const authClient = useAuthClient();
+  const { passkeySupported, loading } = usePasskeySupport();
+
+  async function handleEmailLogin() {
+    const response = await authClient.login({
+      identifier: 'user@example.com',
+      passkeyAvailable: passkeySupported,
+    });
+
+    if (response.ok) {
+      await refreshSession();
+    }
+  }
+
+  return (
+    <button disabled={loading} onClick={() => void handleEmailLogin()}>
+      Sign in
+    </button>
+  );
+}
+```
+
+## Built-In Routes
+
+`AuthRoutes` currently includes:
 
 - `/login`
-- `/mfaLogin`
 - `/passKeyLogin`
+- `/verifyPhoneOTP`
+- `/verifyEmailOTP`
+- `/verify-magiclink`
 - `/registerPasskey`
-- `/verifyOTP`
+- `/magiclinks-sent`
 
-Each route includes a pre-built UI and expects your backend to expose compatible endpoints.
+These are optional UI wrappers over the same SDK primitives the package now exports for custom flows.
 
----
+## Backend Expectations
 
-## Customization
+This package assumes a Seamless Auth-compatible backend with the auth adapter mounted at `/auth`.
 
-You can override the included UI screens by:
+- Requests target `${apiHost}/auth/...`
+- `apiHost` may be provided with or without a trailing slash
+- Requests are sent with `credentials: 'include'`
+- `AuthProvider` validates the current session by calling `/users/me` on load
 
-- Copying the component source from the package
-- Creating your own version
-- Replacing the component in your app
+The built-in flows assume compatible endpoints for:
 
----
+- `/login`
+- `DELETE /logout` for the current session
+- `DELETE /logout/all` for every session owned by the current user
+- `/registration/register`
+- `/webAuthn/login/start`
+- `/webAuthn/login/finish`
+- `/webAuthn/register/start`
+- `/webAuthn/register/finish`
+- `/otp/generate-phone-otp`
+- `/otp/generate-email-otp`
+- `/otp/verify-phone-otp`
+- `/otp/verify-email-otp`
+- `/magic-link`
+- `/magic-link/check`
+- `/magic-link/verify/:token`
+- `/oauth/providers`
+- `/oauth/:providerId/start`
+- `/oauth/:providerId/callback`
+- `/step-up/status`
+- `/step-up/webauthn/start`
+- `/step-up/webauthn/finish`
+- `/users/me`
+- `/users/credentials`
+- `/users/delete`
 
 ## Notes
 
-- This package **does not** create its own `<BrowserRouter>` or `<Routes>`.
-- It is designed to be fully compatible with your existing routing tree.
-- The `AuthProvider` automatically calls `/users/me` on load to validate session.
-
----
+- This package does not create its own `<BrowserRouter>`.
+- It is designed to fit into your app’s existing routing tree.
+- The quickest path is `AuthProvider` + `AuthRoutes`.
+- The most flexible path is `AuthProvider` + custom UI using `useAuth()`, `useAuthClient()`, and `usePasskeySupport()`.
 
 ## License
 
-MIT
+AGPL-3.0-only

package/dist/AuthProvider.d.ts

@@ -1,44 +1,36 @@
+import { FinishOAuthLoginInput, OAuthProvidersResult, StartOAuthLoginInput, StartOAuthLoginResult, StepUpWithPasskeyPrfResult, StepUpStatus, StepUpVerificationResult } from '@/client/createSeamlessAuthClient';
+import { PasskeyPrfInput } from '@/client/webauthnPrf';
+import { Credential, Organization, User } from '@/types';
 import React, { ReactNode } from 'react';
-import { AuthMode } from './fetchWithAuth';
-import { AuthenticatorTransportFuture, CredentialDeviceType } from '@simplewebauthn/browser';
-export interface User {
-    id: string;
-    email: string;
-    phone: string;
-    roles?: string[];
-}
-type AuthToken = {
-    oneTimeToken: string;
-    expiresAt: string;
-};
 export interface AuthContextType {
     user: User | null;
-    logout: () => void;
-    deleteUser: () => void;
+    logout: () => Promise<void>;
+    logoutAllSessions: () => Promise<void>;
+    deleteUser: () => Promise<void>;
+    refreshSession: () => Promise<void>;
     isAuthenticated: boolean;
     hasRole: (role: string) => boolean | undefined;
+    hasScopedRole: (role: string | string[]) => boolean | undefined;
     apiHost: string;
-    token: AuthToken | null;
     markSignedIn: () => void;
     hasSignedInBefore: boolean;
-    mode: AuthMode;
     credentials: Credential[];
+    organizations: Organization[];
+    activeOrganization: Organization | null;
+    switchOrganization: (organizationId: string) => Promise<void>;
+    listOAuthProviders: () => Promise<OAuthProvidersResult>;
+    startOAuthLogin: (input: StartOAuthLoginInput) => Promise<StartOAuthLoginResult>;
+    finishOAuthLogin: (input: FinishOAuthLoginInput) => Promise<void>;
+    stepUpStatus: StepUpStatus | null;
     updateCredential: (credential: Credential) => Promise<Credential>;
     deleteCredential: (credentialId: string) => Promise<void>;
+    login: (identifier: string, passkeyAvailable: boolean) => Promise<Response | null>;
+    handlePasskeyLogin: () => Promise<boolean>;
+    refreshStepUpStatus: () => Promise<StepUpStatus | null>;
+    verifyStepUpWithPasskey: () => Promise<StepUpVerificationResult>;
+    verifyStepUpWithPasskeyPrf: (input: PasskeyPrfInput) => Promise<StepUpWithPasskeyPrfResult>;
     loading: boolean;
 }
-export interface Credential {
-    id: string;
-    counter: number;
-    transports?: AuthenticatorTransportFuture[];
-    deviceType: CredentialDeviceType;
-    backedup: boolean;
-    friendlyName: string | null;
-    lastUsedAt: Date | null;
-    platform: string | null;
-    browser: string | null;
-    deviceInfo: string | null;
-}
 /**
  * Returns the current context
  * @returns {AuthContextType} AuthContext
@@ -48,7 +40,6 @@ interface AuthProviderProps {
     children: ReactNode;
     apiHost: string;
     autoDetectPreviousSignin?: boolean;
-    mode?: AuthMode;
 }
 export declare const AuthProvider: React.FC<AuthProviderProps>;
 export {};