@tidecloak/react 0.9.11 → 0.9.13

package/README.md

@@ -1,23 +1,25 @@
 # TideCloak React SDK
 
-Secure your React app with TideCloak: authentication, session management, and data encryption—all in minutes.
+Secure your React app with TideCloak: authentication, session management, data encryption, and role-based access.
 
 ---
 
 ## 1. Prerequisites
 
-Before you begin, ensure you have:
+Before you begin, ensure you have the following:
 
-- React 18 or later
-- Node.js >=18.17.0 or later
-- A running TideCloak server.
-- A registered client in your realm.
+* **React 18** or later
+* **Node.js ≥18.17.0**
+* A [running](https://github.com/tide-foundation/tidecloak-gettingstarted) TideCloak server you have admin control over
+* IGA enabled realm
+* A registered client in your realm with default user contexts approved and committed
+* A valid Keycloak adapter JSON file (e.g., `tidecloakAdapter.json`)
 
 ---
 
-## 2. Install the SDK
+## 2. Install `@tidecloak/react`
 
-Add the React package to your project:
+Add the TideCloak React SDK to your project:
 
 ```bash
 npm install @tidecloak/react
@@ -27,41 +29,121 @@ yarn add @tidecloak/react
 
 This bundle provides:
 
-- `<TideCloakProvider>` — application-level context.
-- `useTideCloak()` hook — access tokens and auth actions.
-- `<Authenticated>` / `<Unauthenticated>` — UI guards.
+* `<TideCloakProvider>` — application-level context
+* `useTideCloak()` hook — access tokens and auth actions
+* `<Authenticated>` / `<Unauthenticated>` — UI guards
+* `doEncrypt()` / `doDecrypt()` — tag-based encryption/decryption
 
 ---
 
 ## 3. Initialize the Provider
 
-Wrap your root component in `<TideCloakProvider>` to load adapter settings and bootstrap auth:
+Wrap your app’s root with `<TideCloakProvider>` to enable authentication context throughout the component tree.
+
+If you're using React Router, your setup might look like this:
+
+**File:** `src/App.tsx`
 
 ```tsx
 import React from 'react';
+import { BrowserRouter, Routes, Route } from 'react-router-dom';
 import { TideCloakProvider } from '@tidecloak/react';
 import adapter from '../tidecloakAdapter.json';
+import Home from './pages/Home';
+import RedirectPage from './pages/auth/RedirectPage';
 
 export default function App() {
   return (
     <TideCloakProvider config={adapter}>
-      <YourApp />
+      <BrowserRouter>
+        <Routes>
+          <Route path="/" element={<Home />} />
+          <Route path="/auth/redirect" element={<RedirectPage />} />
+          {/* Add additional routes here */}
+        </Routes>
+      </BrowserRouter>
     </TideCloakProvider>
   );
 }
 ```
 
-**What it does:**
+> ⚠️ If you don't define a route at `/auth/redirect`, and you're using the default `redirectUri`, your app **will break after login/logout**. Either create this route or override `redirectUri` in the provider config.
+>
+> If you override the `redirectUri`, you **must** ensure that the custom path exists in your router. Otherwise, the app will redirect to a non-existent route and fail.
+
+---
+
+## 4. Redirect URI Handling
+
+TideCloak supports an optional `redirectUri` config field. This defines where the user is sent after login/logout.
+
+If omitted, it defaults to:
+
+```ts
+`${window.location.origin}/auth/redirect`
+```
+
+> Example: If your app runs at `http://localhost:3000`, then by default the redirect path is `http://localhost:3000/auth/redirect`.
 
-- **Loads** your adapter JSON.
-- **Initializes** internal auth flows and listeners.
-- **Provides** auth state & methods via React Context.
+You must **create this route** if you use the default, or explicitly override it:
+
+```tsx
+<TideCloakProvider config={{ ...adapter, redirectUri: 'https://yourapp.com/auth/callback' }}>
+  <YourApp />
+</TideCloakProvider>
+```
+
+> ⚠️ If you override the `redirectUri`, make sure the specified path exists in your app. Missing this route will cause failed redirects.
+
+### Example: Redirect Handling Page
+
+**File:** `src/pages/auth/RedirectPage.tsx`
+
+```tsx
+import { useEffect } from 'react';
+import { useNavigate } from 'react-router-dom';
+import { useTideCloak } from '@tidecloak/react';
+
+export default function RedirectPage() {
+  const { authenticated, isInitializing, logout } = useTideCloak();
+  const navigate = useNavigate();
+
+  useEffect(() => {
+    const params = new URLSearchParams(window.location.search);
+    if (params.get("auth") === "failed") {
+      sessionStorage.setItem("tokenExpired", "true");
+      logout();
+    }
+  }, []);
+
+  useEffect(() => {
+    if (!isInitializing) {
+      navigate(authenticated ? '/home' : '/');
+    }
+  }, [authenticated, isInitializing, navigate]);
+
+  return (
+    <div style={{
+      minHeight: '100vh',
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      fontSize: '1rem',
+      color: '#555',
+    }}>
+      <p>Waiting for authentication...</p>
+    </div>
+  );
+}
+```
+
+**Description:** This page helps finalize the login or logout flow, and also reacts to token expiration events that may have triggered a redirect. It's required if you're using the default `redirectUri`. If you override the redirect URI, the file is optional—but the **route** for the redirect **must** still exist in your app.
 
 ---
 
-## 4. Using the `useTideCloak` Hook
+## 5. Using the `useTideCloak` Hook
 
-Use this hook anywhere to manage auth:
+Use this hook anywhere in your component tree to manage authentication:
 
 ```tsx
 import { useTideCloak } from '@tidecloak/react';
@@ -78,6 +160,8 @@ function Header() {
     getValueFromIdToken,
     hasRealmRole,
     hasClientRole,
+    doEncrypt,
+    doDecrypt,
   } = useTideCloak();
 
   return (
@@ -98,26 +182,24 @@ function Header() {
 }
 ```
 
-**Key methods & props:**
-
-| Name                               | Type                                         | Description                                                             |
-| ---------------------------------- | -------------------------------------------- | ----------------------------------------------------------------------- |
-| `authenticated`                    | `boolean`                                    | Whether the user is logged in.                                          |
-| `login()` / `logout()`             | `() => void`                                 | Trigger the login or logout flows.                                      |
-| `token`, `tokenExp`                | `string`, `number`                           | Access token and its expiration timestamp.                              |
-| Automatic token refresh            | built-in                                     | Tokens refresh silently on expiration—no manual setup needed.           |
-| `refreshToken()`                   | `() => Promise<boolean>`                     | Force a silent token renewal.                                           |
-| `getValueFromToken(key)`           | `(key: string) => any`                       | Read a custom claim from the access token.                              |
-| `getValueFromIdToken(key)`         | `(key: string) => any`                       | Read a custom claim from the ID token.                                  |
-| `hasRealmRole(role)`               | `(role: string) => boolean`                  | Check a realm-level role.                                               |
-| `hasClientRole(role, client?)`     | `(role: string, client?: string) => boolean` | Check a client-level role; defaults to your app’s client ID if omitted. |
-| `doEncrypt(data)``doDecrypt(data)` | `(data: any) => Promise<any>`                | Encrypt or decrypt payloads via TideCloak’s built-in service.           |
+| Name                                  | Type                                         | Description                                                             |
+| ------------------------------------- | -------------------------------------------- | ----------------------------------------------------------------------- |
+| `authenticated`                       | `boolean`                                    | Whether the user is logged in.                                          |
+| `login()` / `logout()`                | `() => void`                                 | Trigger the login or logout flows.                                      |
+| `token`, `tokenExp`                   | `string`, `number`                           | Access token and its expiration timestamp.                              |
+| Automatic token refresh               | built-in                                     | Tokens refresh silently on expiration—no manual setup needed.           |
+| `refreshToken()`                      | `() => Promise<boolean>`                     | Force a silent token renewal.                                           |
+| `getValueFromToken(key)`              | `(key: string) => any`                       | Read a custom claim from the access token.                              |
+| `getValueFromIdToken(key)`            | `(key: string) => any`                       | Read a custom claim from the ID token.                                  |
+| `hasRealmRole(role)`                  | `(role: string) => boolean`                  | Check a realm-level role.                                               |
+| `hasClientRole(role, client?)`        | `(role: string, client?: string) => boolean` | Check a client-level role; defaults to your app’s client ID if omitted. |
+| `doEncrypt(data)` / `doDecrypt(data)` | `(data: any) => Promise<any>`                | Encrypt or decrypt payloads via TideCloak’s built-in service.           |
 
 ---
 
-## 5. Guard Components
+## 6. Guard Components
 
-Use out-of-the-box components to show or hide content:
+Use these components to show or hide content based on authentication state:
 
 ```tsx
 import { Authenticated, Unauthenticated } from '@tidecloak/react';
@@ -138,93 +220,38 @@ function Dashboard() {
 }
 ```
 
-- `<Authenticated>`: renders children only when `authenticated === true`.
-- `<Unauthenticated>`: renders children only when `authenticated === false`.
+* `<Authenticated>`: renders children only when `authenticated === true`
+* `<Unauthenticated>`: renders children only when `authenticated === false`
 
 ---
 
-## 6. Encrypting & Decrypting Data
+## 7. Encrypting & Decrypting Data
 
-TideCloak lets you protect sensitive fields with **tag-based** encryption. You pass in an array of `{ data, tags }` objects and receive an array of encrypted strings (or vice versa for decryption).
-
-### Syntax Overview
+Protect sensitive payloads using tag-based encryption/decryption:
 
 ```ts
-// Encrypt one or more payloads:
-const encryptedArray: string[] = await doEncrypt([
-  { data: /* any JSON-serializable value */, tags: ['tag1', 'tag2'] },
-  // …
+// Encrypt:
+const encryptedArray = await doEncrypt([
+  { data: { email: 'user@example.com' }, tags: ['email'] },
 ]);
 
-// Decrypt one or more encrypted blobs:
-const decryptedArray: any[] = await doDecrypt([
-  { encrypted: /* string from encrypt() */, tags: ['tag1', 'tag2'] },
-  // …
+// Decrypt:
+const decryptedArray = await doDecrypt([
+  { encrypted: encryptedArray[0], tags: ['email'] },
 ]);
 ```
 
-> **Order guarantee**: the returned array matches the input order.
-
----
-
-### Encryption Example
-
-```tsx
-import { useTideCloak } from '@tidecloak/react';
-
-async function encryptExamples() {
-  const { doEncrypt } = useTideCloak();
-
-  // Simple single-item encryption:
-  const [encryptedDob] = await doEncrypt([
-    { data: '2005-03-04', tags: ['dob'] }
-  ]);
-
-  // Multi-field encryption:
-  const encryptedFields = await doEncrypt([
-    { data: '10 Smith Street', tags: ['street'] },
-    { data: 'Southport', tags: ['suburb'] },
-    { data: { full: '20 James Street – Burleigh Heads' }, tags: ['street', 'suburb'] }
-  ]);
-}
-```
-
-> **Permissions**: Users need roles matching **every** tag on a payload. A payload tagged `['street','suburb']` requires both the `tide_street.selfencrypt` and `tide_suburb.selfencrypt` roles.
+> **Permissions**: Encryption requires `tide_<tag>.selfencrypt`; decryption requires `tide_<tag>.selfdecrypt`.
+> **Order guarantee**: Output preserves input order.
 
 ---
 
-### Decryption Example
+## 8. Advanced & Best Practices
 
-```tsx
-import { useTideCloak } from '@tidecloak/react';
-
-async function decryptExamples(encryptedFields: string[]) {
-  const { doDecrypt } = useTideCloak();
-
-  // Single-item decryption:
-  const [decryptedDob] = await doDecrypt([
-    { encrypted: encryptedFields[0], tags: ['dob'] }
-  ]);
-
-  // Multi-field decryption:
-  const decryptedFields = await doDecrypt([
-    { encrypted: encryptedFields[0], tags: ['street'] },
-    { encrypted: encryptedFields[1], tags: ['suburb'] },
-    { encrypted: encryptedFields[2], tags: ['street','suburb'] }
-  ]);
-}
-```
-
-> **Permissions**: Like encryption, decryption requires the same tag-based roles (`tide_street.selfdecrypt`, `tide_suburb.selfdecrypt`, etc.).
+* **Auto-Refresh**: built-in, no manual timer setup required
+* **Error Handling**: check `initError` from `useTideCloak`
+* **Custom Claims**: access token fields with `getValueFromToken()` / `getValueFromIdToken()`
+* **Role-Based UI**: combine `hasRealmRole`, `hasClientRole`, and guard components
+* **Lazy Initialization**: optionally wrap `<TideCloakProvider>` around only protected routes
 
 ---
-
-## 7. Advanced & Best Practices
-
-- **Auto-Refresh**: built into the provider—no manual token timers needed.
-- **Error Handling**: use the `initError` value from `useTideCloak` to catch startup issues.
-- **Custom Claims**: store app-specific data in JWT claims and access via `getValueFromToken()` / `getValueFromIdToken()`.
-- **Role-Based Access**: combine `hasRealmRole` and `hasClientRole` with guard components for fine-grained control.
-- **Lazy Initialization**: wrap `<TideCloakProvider>` around only authenticated sections in large apps.
-
----

package/dist/cjs/contexts/TideCloakProvider.js

@@ -0,0 +1,3 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { TideCloakContextProvider } from "./TideCloakContextProvider";
+export const TideCloakProvider = ({ config, children }) => (_jsx(TideCloakContextProvider, { config: config, children: children }));

package/dist/cjs/index.js

@@ -1,10 +1,5 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-import { TideCloakContextProvider, useTideCloakContext, } from './contexts/TideCloakContextProvider';
-/**
- * Wrap your app and bootstrap TideCloak with the given config object.
- * tidecloak-js expects a plain JSON config, so we type config as Record<string, any>.
- */
-export const TideCloakProvider = ({ config, children }) => (_jsx(TideCloakContextProvider, { config: config, children: children }));
+import { useTideCloakContext, } from './contexts/TideCloakContextProvider';
+export { TideCloakContextProvider } from './contexts/TideCloakContextProvider';
 /**
  * Hook to access authentication state and helpers.
  */

package/dist/esm/contexts/TideCloakProvider.js

@@ -0,0 +1,3 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { TideCloakContextProvider } from "./TideCloakContextProvider";
+export const TideCloakProvider = ({ config, children }) => (_jsx(TideCloakContextProvider, { config: config, children: children }));

package/dist/esm/index.js

@@ -1,10 +1,5 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-import { TideCloakContextProvider, useTideCloakContext, } from './contexts/TideCloakContextProvider';
-/**
- * Wrap your app and bootstrap TideCloak with the given config object.
- * tidecloak-js expects a plain JSON config, so we type config as Record<string, any>.
- */
-export const TideCloakProvider = ({ config, children }) => (_jsx(TideCloakContextProvider, { config: config, children: children }));
+import { useTideCloakContext, } from './contexts/TideCloakContextProvider';
+export { TideCloakContextProvider } from './contexts/TideCloakContextProvider';
 /**
  * Hook to access authentication state and helpers.
  */

package/dist/types/contexts/TideCloakProvider.d.ts

@@ -0,0 +1,8 @@
+import { ReactNode, FC } from "react";
+interface TideCloakProviderProps {
+    config: Record<string, any>;
+    children: ReactNode;
+}
+export declare const TideCloakProvider: FC<TideCloakProviderProps>;
+export {};
+//# sourceMappingURL=TideCloakProvider.d.ts.map

package/dist/types/contexts/TideCloakProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TideCloakProvider.d.ts","sourceRoot":"","sources":["../../../src/contexts/TideCloakProvider.tsx"],"names":[],"mappings":"AAAA,OAAc,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC;AAG7C,UAAU,sBAAsB;IAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC5B,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED,eAAO,MAAM,iBAAiB,EAAE,EAAE,CAAC,sBAAsB,CAIxD,CAAC"}

package/dist/types/index.d.ts

@@ -1,13 +1,6 @@
-import React, { ReactNode, FC } from 'react';
+import React from 'react';
 import { useTideCloakContext } from './contexts/TideCloakContextProvider';
-/**
- * Wrap your app and bootstrap TideCloak with the given config object.
- * tidecloak-js expects a plain JSON config, so we type config as Record<string, any>.
- */
-export declare const TideCloakProvider: FC<{
-    config: Record<string, any>;
-    children: ReactNode;
-}>;
+export { TideCloakContextProvider } from './contexts/TideCloakContextProvider';
 /**
  * Hook to access authentication state and helpers.
  */

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC;AAC7C,OAAO,EAEL,mBAAmB,EACpB,MAAM,qCAAqC,CAAC;AAE7C;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,EAAE,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAAC,QAAQ,EAAE,SAAS,CAAA;CAAE,CAKpF,CAAC;AAEJ;;GAEG;AACH,eAAO,MAAM,YAAY,4BAAsB,CAAC;AAEhD,wBAAgB,aAAa,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAAE,GAAG,KAAK,CAAC,SAAS,CAI1F;AAED,wBAAgB,eAAe,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAAE,GAAG,KAAK,CAAC,SAAS,CAI5F"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAwB,MAAM,OAAO,CAAC;AAC7C,OAAO,EACL,mBAAmB,EACpB,MAAM,qCAAqC,CAAC;AAE7C,OAAQ,EAAE,wBAAwB,EAAE,MAAM,qCAAqC,CAAC;AAEhF;;GAEG;AACH,eAAO,MAAM,YAAY,4BAAsB,CAAC;AAEhD,wBAAgB,aAAa,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAAE,GAAG,KAAK,CAAC,SAAS,CAI1F;AAED,wBAAgB,eAAe,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAAE,GAAG,KAAK,CAAC,SAAS,CAI5F"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tidecloak/react",
-  "version": "0.9.11",
+  "version": "0.9.13",
   "description": "TideCloak client-side React SDK",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -48,6 +48,6 @@
     "@types/react-dom": "^19.1.6"
   },
   "dependencies": {
-    "@tidecloak/js": "^0.9.11"
+    "@tidecloak/js": "^0.9.13"
   }
 }