@versini/auth-provider 8.0.3 → 8.0.5

package/README.md

@@ -1,3 +1,149 @@
 # @versini/auth-provider
 
-This package provides a simple authentication provider for your application.
+High-level React authentication components & hooks supporting password (PKCE Code) and Passkey (WebAuthn) flows, with optional Auth0 integration. Built on the primitives from `@versini/auth-common`.
+
+## Install
+
+```bash
+pnpm add @versini/auth-provider @versini/auth-common react react-dom
+```
+
+Peer deps: `react` (>= 19) & `react-dom`.
+
+## Packages Relationship
+
+```
+@versini/auth-provider  ->  @versini/auth-common (utilities, constants)
+												 ->  @versini/ui-hooks (local storage abstraction)
+```
+
+## Features
+
+- PKCE Code + Refresh token flow
+- Passkey (WebAuthn) registration & authentication
+- Silent access token refresh with refresh token rotation
+- Role / permission helpers (re-export of `isGranted` & `AUTH_TYPES`)
+- Opt-in Auth0 provider wrapper
+- Local storage isolation per `clientId`
+- Timezone & build metadata banner injection (in distributed bundles)
+
+## Quick Start (Custom Auth Backend)
+
+```tsx
+import { AuthProvider } from "@versini/auth-provider";
+
+function App() {
+  return (
+    <AuthProvider clientId="my-web-app" sessionExpiration="3600" debug>
+      <MainRoutes />
+    </AuthProvider>
+  );
+}
+```
+
+Inside your components:
+
+```tsx
+import { useAuth } from "@versini/auth-provider/hooks";
+
+export function Profile() {
+  const { user, isAuthenticated, login, logout, getAccessToken } = useAuth();
+
+  if (!isAuthenticated) {
+    return <button onClick={() => login("alice", "p@ssw0rd")}>Login</button>;
+  }
+  return (
+    <div>
+      <p>User: {user?.username}</p>
+      <button onClick={logout}>Logout</button>
+      <button
+        onClick={async () => {
+          const token = await getAccessToken();
+          console.log("access", token.slice(0, 20) + "...");
+        }}
+      >
+        Get Access Token
+      </button>
+    </div>
+  );
+}
+```
+
+## Passkey (WebAuthn) Flow
+
+```tsx
+const { registeringForPasskey, loginWithPasskey } = useAuth();
+
+// After user authenticates with password you can offer passkey registration:
+await registeringForPasskey();
+
+// Later, user can login directly with passkey:
+await loginWithPasskey();
+```
+
+## Auth0 Integration
+
+```tsx
+import { Auth0Provider } from "@versini/auth-provider/auth0";
+
+<Auth0Provider
+  domain="YOUR_DOMAIN"
+  clientId="YOUR_CLIENT_ID"
+  authorizationParams={{ redirect_uri: window.location.origin }}
+>
+  <App />
+</Auth0Provider>;
+```
+
+All Auth hooks still come from `@versini/auth-provider/hooks`.
+
+## Public API Summary
+
+- `<AuthProvider />` – Core provider. Props:
+  - `clientId: string` (required)
+  - `sessionExpiration?: string` (TTL hint sent to backend)
+  - `domain?: string` (multi-tenant / custom domain support)
+  - `debug?: boolean` (enables internal logging via `useLogger`)
+  - `endpoint?: string` (override default auth service URL)
+- Hooks (from `hooks` entry):
+  - `useAuth()` – Returns `AuthContextProps`:
+    - state: `isLoading`, `isAuthenticated`, `user`, `logoutReason`, `authenticationType`
+    - methods: `login(username, password)`, `logout()`, `getAccessToken()`, `getIdToken()`, `registeringForPasskey()`, `loginWithPasskey()`
+- Auth0:
+  - `<Auth0Provider />` – Wraps children and injects Auth0 context + shared `useAuth` hook wiring.
+- Re-exports from `@versini/auth-common`:
+  - `AUTH_TYPES`, `isGranted`
+
+## Storage Strategy
+
+Local storage keys are namespaced: `@@auth@@::<clientId>::@@<token-type>@@`.
+On logout or token invalidation all related keys are purged atomically (`removeStateAndLocalStorage`).
+
+## Token Refresh
+
+`getAccessToken()` validates the existing access token; if expired/invalid it attempts a silent refresh via `TokenManager.refreshtoken()`. Failure triggers a forced logout (security-first principle).
+
+## Error & Security Principles
+
+- Deny-by-default: unauthorized or invalid token state leads to logout.
+- All network operations funnel through typed helpers; unexpected responses cause cleanup.
+- No sensitive values are logged unless `debug` is enabled (still avoid including raw tokens in production logs).
+- PKCE flow ensures authorization code interception resistance.
+
+## Bundling Notes
+
+Entry files are emitted without hashes (`index.js`, `auth.js`, `auth0.js`, `hooks.js`) for stable package exports; internal split chunks are hashed (`chunks/[name].[hash].js`). This is intentional for library consumption stability.
+
+## TypeScript
+
+Distributed ESM with full `.d.ts` declarations; strict types encourage safe usage. Avoid `any`; leverage `AuthContextProps` for context consumers.
+
+## Roadmap / Ideas
+
+- SSR helpers for preloading user session
+- Optional cookie-based storage abstraction
+- Enhanced role/permission model (attribute-based access)
+
+## License
+
+MIT © gizmette.com

package/dist/auth.js

@@ -1,18 +1,18 @@
 var Pe = Object.defineProperty;
 var Ce = (e, t, n) => t in e ? Pe(e, t, { enumerable: !0, configurable: !0, writable: !0, value: n }) : e[t] = n;
 var K = (e, t, n) => Ce(e, typeof t != "symbol" ? t + "" : t, n);
-import { jsx as H } from "react/jsx-runtime";
-import { at as ie, st as ve, K as T, ot as M, nt as C, Ye as D, ct as Ue } from "./index-DxGUVOpC.js";
+import { jsx as V } from "react/jsx-runtime";
+import { HEADERS as ie, decodeToken as ve, JWT as T, API_TYPE as M, AUTH_TYPES as C, verifyAndExtractToken as D, pkceChallengePair as Ue } from "@versini/auth-common";
 import De, { useSyncExternalStore as Le, useCallback as S, useEffect as ce, createContext as $e, useContext as Ke, useReducer as Ye, useRef as Ge } from "react";
-import { AuthHookContext as Ve } from "./AuthHookContext-C9a2AwWZ.js";
+import { AuthHookContext as He } from "./AuthHookContext-C9a2AwWZ.js";
 /*!
-  @versini/auth-provider v8.0.3
+  @versini/auth-provider v8.0.5
   © 2025 gizmette.com
 */
 try {
   window.__VERSINI_AUTH_CLIENT__ || (window.__VERSINI_AUTH_CLIENT__ = {
-    version: "8.0.3",
-    buildTime: "06/02/2025 05:45 PM EDT",
+    version: "8.0.5",
+    buildTime: "09/01/2025 07:37 PM EDT",
     homepage: "https://github.com/aversini/auth-client",
     license: "MIT"
   });
@@ -32,9 +32,9 @@ function F(e) {
   return o;
 }
 function X() {
-  return He.stubThis(globalThis?.PublicKeyCredential !== void 0 && typeof globalThis.PublicKeyCredential == "function");
+  return Ve.stubThis(globalThis?.PublicKeyCredential !== void 0 && typeof globalThis.PublicKeyCredential == "function");
 }
-const He = {
+const Ve = {
   stubThis: (e) => e
 };
 function ue(e) {
@@ -407,7 +407,7 @@ function z(e, t, n) {
     throw new Error("Random bytes length must be >= 16");
   return a[6] = a[6] & 15 | 64, a[8] = a[8] & 63 | 128, Qe(a);
 }
-const b = "Your session has expired. For your security, please log in again to continue.", tt = "Your session has been successfully terminated.", Q = "Login failed. Please try again.", nt = "Error getting access token, please re-authenticate.", at = "You forgot to wrap your component in <AuthProvider>.", G = "@@auth@@", U = "LOADING", x = "LOGIN", pe = "LOGOUT", L = "success", A = "failure", fe = "include", Te = "POST", ye = "application/json", V = {
+const b = "Your session has expired. For your security, please log in again to continue.", tt = "Your session has been successfully terminated.", Q = "Login failed. Please try again.", nt = "Error getting access token, please re-authenticate.", at = "You forgot to wrap your component in <AuthProvider>.", G = "@@auth@@", U = "LOADING", x = "LOGIN", pe = "LOGOUT", L = "success", A = "failure", fe = "include", Te = "POST", ye = "application/json", H = {
   GET_REGISTRATION_OPTIONS: `mutation GetPasskeyRegistrationOptions(
 	$clientId: String!,
 	$username: String!,
@@ -490,19 +490,19 @@ const b = "Your session has expired. For your security, please log in again to c
 	}`
 }, N = {
   GET_REGISTRATION_OPTIONS: {
-    schema: V.GET_REGISTRATION_OPTIONS,
+    schema: H.GET_REGISTRATION_OPTIONS,
     method: "getPasskeyRegistrationOptions"
   },
   VERIFY_REGISTRATION: {
-    schema: V.VERIFY_REGISTRATION,
+    schema: H.VERIFY_REGISTRATION,
     method: "verifyPasskeyRegistration"
   },
   GET_AUTHENTICATION_OPTIONS: {
-    schema: V.GET_AUTHENTICATION_OPTIONS,
+    schema: H.GET_AUTHENTICATION_OPTIONS,
     method: "getPasskeyAuthenticationOptions"
   },
   VERIFY_AUTHENTICATION: {
-    schema: V.VERIFY_AUTHENTICATION,
+    schema: H.VERIFY_AUTHENTICATION,
     method: "verifyPasskeyAuthentication"
   }
 }, k = async ({
@@ -814,7 +814,7 @@ const P = () => {
   logoutReason: t.payload.logoutReason
 } : e, Tt = ({ children: e }) => {
   const t = ht();
-  return /* @__PURE__ */ H(Ve.Provider, { value: t, children: e });
+  return /* @__PURE__ */ V(He.Provider, { value: t, children: e });
 }, wt = ({
   children: e,
   sessionExpiration: t,
@@ -1083,7 +1083,7 @@ const P = () => {
       }
     return !1;
   };
-  return /* @__PURE__ */ H(pt.Provider, { value: { state: c, dispatch: r }, children: /* @__PURE__ */ H(
+  return /* @__PURE__ */ V(pt.Provider, { value: { state: c, dispatch: r }, children: /* @__PURE__ */ V(
     me.Provider,
     {
       value: {
@@ -1095,7 +1095,7 @@ const P = () => {
         registeringForPasskey: be,
         loginWithPasskey: Ne
       },
-      children: /* @__PURE__ */ H(Tt, { children: e })
+      children: /* @__PURE__ */ V(Tt, { children: e })
     }
   ) });
 };