@tidecloak/js 0.14.32-staging → 0.14.33

package/docs/FRONT_CHANNEL.md

@@ -0,0 +1,227 @@
+# Front-Channel Mode
+
+The simplest way to add TideCloak to your web app. Everything happens in the browser.
+
+---
+
+## What You'll Build
+
+Click login, your users go to TideCloak, they log in, they come back authenticated. That's it.
+
+---
+
+## Quick Start
+
+### 1. Get Your Config File
+
+Download `tidecloak.json` (your client adapter config) from your TideCloak admin console and put it in your app.
+
+### 2. Add Silent SSO Check File
+
+This file is required for silent session checks. It should be auto-copied when you install `@tidecloak/js`, but if it's missing, create `public/silent-check-sso.html`:
+
+```html
+<html><body><script>parent.postMessage(location.href, location.origin)</script></body></html>
+```
+
+### 3. Create a Redirect Page
+
+Create `public/auth/redirect.html`:
+
+```html
+<!DOCTYPE html>
+<html>
+  <head><title>Redirecting...</title></head>
+  <body>
+    <p>Redirecting...</p>
+    <script>window.location.href = "/";</script>
+  </body>
+</html>
+```
+
+### 4. Initialize the SDK
+
+```js
+import { IAMService } from "@tidecloak/js";
+import config from "./tidecloak.json";
+
+// Listen for events. Handlers get the event name first, then its arguments.
+IAMService
+  .on("ready", (_event, loggedIn) => {
+    console.log("Ready! Logged in:", loggedIn);
+    updateUI(loggedIn);
+  })
+  .on("authSuccess", () => {
+    console.log("Login successful");
+  })
+  .on("logout", () => {
+    console.log("Logged out");
+  });
+
+// Start the SDK
+await IAMService.initIAM(config);
+```
+
+### DPoP (opt-in)
+
+DPoP (sender-constrained tokens, [RFC 9449](https://datatracker.ietf.org/doc/html/rfc9449)) binds an access token to a per-session key, so a stolen token can't be replayed. It is **opt-in**: set `useDPoP` and the SDK turns it on; omit it and the SDK requests an ordinary (unbound) token.
+
+> **DPoP is not a flag you can flip in isolation.** Asking for it appends `dpop_jkt` to the authorization request, and the realm then issues a token carrying `typ: "DPoP"` and `cnf.jkt`. Such a token is **invalid** if it is later presented as a plain `Authorization: Bearer …`, and the resource server answers a bare `401`. So enable DPoP only if every call that carries the token attaches a `DPoP:` proof (use `IAMService.secureFetch`, which does this for you). This is why the SDK will not turn DPoP on for you.
+
+```js
+// Opt in, enforced: init fails if the realm doesn't advertise DPoP support
+await IAMService.initIAM({ ...config, useDPoP: { mode: "strict" } });
+
+// Use DPoP only when the realm supports it, otherwise fall back to bearer:
+await IAMService.initIAM({ ...config, useDPoP: { mode: "auto" } });
+
+// Pick the proof signing algorithm (default "ES256"):
+await IAMService.initIAM({ ...config, useDPoP: { mode: "strict", alg: "EdDSA" } });
+
+// No DPoP, a plain unbound access token (the default)
+await IAMService.initIAM({ ...config });
+```
+
+| `useDPoP` value            | Behavior                                                                 |
+| -------------------------- | ------------------------------------------------------------------------ |
+| *(omitted)* / `false`      | **Default.** No DPoP. No `dpop_jkt`, plain unbound access token.          |
+| `{ mode: "auto" }`         | Use DPoP when the realm advertises it; otherwise fall back to bearer.    |
+| `{ mode: "strict" }`       | Enforce DPoP; init fails if the realm lacks DPoP support.                |
+| `{ mode: …, alg }`         | As above, with a specific proof algorithm (`ES256` default).            |
+
+> Your **resource server** must validate DPoP proofs for the binding to be meaningful. See [`lib/README.md`](../lib/README.md#dpop-resource-server-setup) for serving `tide_dpop_auth.html`.
+
+### 5. Add Login/Logout Buttons
+
+```js
+document.getElementById("login-btn").onclick = () => IAMService.doLogin();
+document.getElementById("logout-btn").onclick = () => IAMService.doLogout();
+```
+
+---
+
+## Everything You Can Do
+
+```js
+// Check auth state
+IAMService.isLoggedIn();           // Is user logged in?
+
+// Get tokens
+await IAMService.getToken();       // Access token (for API calls)
+IAMService.getIDToken();           // ID token
+
+// Get user info
+IAMService.getName();              // Username
+IAMService.getValueFromToken("email");
+IAMService.getValueFromIDToken("name"); // getValueFromIdToken also works
+
+// Check roles
+IAMService.hasRealmRole("admin");
+IAMService.hasClientRole("editor");
+
+// Auth actions
+IAMService.doLogin();
+IAMService.doLogout();
+await IAMService.updateIAMToken(); // Refresh token
+
+// Encryption (if configured)
+await IAMService.doEncrypt([{ data: "secret", tags: ["personal"] }]);
+await IAMService.doDecrypt([{ encrypted: "...", tags: ["personal"] }]);
+```
+
+---
+
+## Events
+
+Every handler is called with the event name first, then the event's arguments.
+
+```js
+IAMService
+  .on("ready", (_event, loggedIn) => {
+    // SDK is ready - loggedIn is true/false
+  })
+  .on("authSuccess", () => {
+    // User logged in
+  })
+  .on("authError", (_event, err) => {
+    // Login failed
+  })
+  .on("logout", () => {
+    // User logged out
+  })
+  .on("tokenExpired", () => {
+    // Token expired - SDK will try to refresh
+  });
+```
+
+---
+
+## Encryption
+
+Protect sensitive data with tag-based encryption:
+
+```js
+// Encrypt one or more items
+const encrypted = await IAMService.doEncrypt([
+  { data: "10 Smith Street", tags: ["address"] },
+  { data: "john@example.com", tags: ["email"] },
+]);
+
+// Decrypt
+const decrypted = await IAMService.doDecrypt([
+  { encrypted: encrypted[0], tags: ["address"] },
+  { encrypted: encrypted[1], tags: ["email"] },
+]);
+```
+
+**Important:**
+- `data` must be a string or `Uint8Array` (not an object - use `JSON.stringify()` first)
+- Users need `_tide_<tag>.selfencrypt` / `_tide_<tag>.selfdecrypt` roles
+- Output order matches input order
+- Both methods take an optional signed decryption policy (`Uint8Array`) as a second argument. See [Policy-Protected Encryption](../lib/README.md#policy-protected-encryption).
+
+### Encrypt Objects
+
+```js
+// Wrong - objects not allowed
+await IAMService.doEncrypt([{ data: { name: "John" }, tags: ["user"] }]);
+
+// Right - stringify first
+await IAMService.doEncrypt([{ data: JSON.stringify({ name: "John" }), tags: ["user"] }]);
+```
+
+---
+
+## Custom Redirect Path
+
+By default, users go to `/auth/redirect` after login. To change this:
+
+```js
+await IAMService.initIAM({
+  ...config,
+  redirectUri: "https://myapp.com/callback"
+});
+```
+
+---
+
+## Troubleshooting
+
+**Blank page after login**
+
+Make sure you have a page at `/auth/redirect` and your redirect URI is registered in TideCloak.
+
+**"silent-check-sso.html not found" or silent SSO fails**
+
+Create `public/silent-check-sso.html` with this content:
+```html
+<html><body><script>parent.postMessage(location.href, location.origin)</script></body></html>
+```
+
+**Token not available**
+
+Wait for the `ready` event before using tokens.
+
+**Encryption fails**
+
+Make sure your `tidecloak.json` includes `vendorId` and the `client-origin-auth-{origin}` for your app's origin.

package/docs/HYBRID_MODE.md

@@ -0,0 +1,185 @@
+# Hybrid/BFF Mode
+
+For apps where security is critical. Your backend handles tokens - they never touch the browser.
+
+---
+
+## What You'll Build
+
+User clicks login, goes to TideCloak, logs in, comes back. But instead of tokens going to the browser, they go to your server. Your server creates a session, and the browser just gets a session cookie.
+
+---
+
+## When to Use This
+
+- You're handling sensitive data (financial, medical, etc.)
+- You don't want tokens in the browser at all
+- Your backend needs to make API calls on behalf of users
+- You need server-side session control
+
+---
+
+## Quick Start
+
+### 1. Set Up Your Config
+
+```js
+const hybridConfig = {
+  authMode: "hybrid",
+  oidc: {
+    authorizationEndpoint: "https://auth.example.com/realms/myrealm/protocol/openid-connect/auth",
+    clientId: "my-app",
+    redirectUri: "https://myapp.com/auth/callback",
+    scope: "openid profile email"
+  },
+  tokenExchange: {
+    endpoint: "/api/authenticate"  // Your backend will handle this
+  }
+};
+```
+
+### 2. Login Page
+
+```js
+import { IAMService } from "@tidecloak/js";
+
+await IAMService.loadConfig(hybridConfig);
+
+document.getElementById("login-btn").onclick = () => {
+  IAMService.doLogin("/dashboard");  // Where to go after login
+};
+```
+
+### 3. Callback Page
+
+```js
+import { IAMService } from "@tidecloak/js";
+
+const loggedIn = await IAMService.initIAM(hybridConfig);
+
+if (loggedIn) {
+  // Success - redirect to where user wanted to go
+  window.location.href = IAMService.getReturnUrl() || "/";
+} else {
+  // Failed
+  document.getElementById("error").textContent = "Login failed";
+}
+```
+
+### 4. Build Your Backend Endpoint
+
+Your `/api/authenticate` endpoint receives:
+
+```json
+{
+  "accessToken": "{\"code\":\"AUTH_CODE\",\"code_verifier\":\"PKCE_VERIFIER\",\"redirect_uri\":\"...\"}",
+  "provider": "tidecloak-auth"
+}
+```
+
+Your backend should:
+1. Parse the JSON in `accessToken`
+2. Exchange the code with TideCloak
+3. Store tokens server-side
+4. Create a session for the user
+
+**Express.js example:**
+
+```js
+app.post('/api/authenticate', async (req, res) => {
+  const authData = JSON.parse(req.body.accessToken);
+
+  // Exchange code for tokens
+  const tokenResponse = await fetch(
+    'https://auth.example.com/realms/myrealm/protocol/openid-connect/token',
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({
+        grant_type: 'authorization_code',
+        client_id: 'my-app',
+        code: authData.code,
+        code_verifier: authData.code_verifier,
+        redirect_uri: authData.redirect_uri,
+      }),
+    }
+  );
+
+  if (!tokenResponse.ok) {
+    return res.status(401).json({ error: 'Token exchange failed' });
+  }
+
+  const tokens = await tokenResponse.json();
+
+  // Store tokens and create session
+  req.session.tokens = tokens;
+  req.session.userId = tokens.sub;
+
+  res.json({ success: true });
+});
+```
+
+---
+
+## What You Can Do (Client-Side)
+
+Since tokens are on your server, most methods won't work in the browser. You can use:
+
+```js
+// Did user complete login?
+IAMService.isLoggedIn();
+
+// Where did user want to go?
+IAMService.getReturnUrl();
+```
+
+---
+
+## What You Can't Do (Client-Side)
+
+These won't work because tokens are on your server:
+
+- `getToken()`, `getIDToken()`
+- `getName()`, `hasRealmRole()`, `hasClientRole()`
+- `getValueFromToken()`, `getValueFromIDToken()` (and its alias `getValueFromIdToken()`)
+- `doEncrypt()`, `doDecrypt()`
+
+Your backend should provide user info via your own API endpoints.
+
+---
+
+## Front-Channel vs Hybrid
+
+| Question | Front-Channel | Hybrid |
+|----------|---------------|--------|
+| Where are tokens? | Browser | Server |
+| Can I use encryption client-side? | Yes | No |
+| Can I check roles client-side? | Yes | No |
+| Is it simpler? | Yes | No |
+| Is it more secure? | Good | Better |
+
+**Use Front-Channel if:**
+- You're building a simple web app
+- You need client-side encryption
+- You want the easiest setup
+
+**Use Hybrid if:**
+- Security is critical
+- You don't trust the browser with tokens
+- Your backend makes API calls on behalf of users
+
+---
+
+## Troubleshooting
+
+**Callback fails**
+
+Check that your `redirect_uri` matches exactly what's registered in TideCloak.
+
+**Session not persisting**
+
+Make sure your backend is setting cookies correctly and they're not being blocked by CORS or same-site policies.
+
+**Backend token exchange fails**
+
+Double-check your TideCloak token endpoint URL and client ID.

package/docs/NATIVE_MODE.md

@@ -0,0 +1,284 @@
+# Native Mode
+
+Build desktop and mobile apps with TideCloak. Works with Electron, Tauri, and React Native.
+
+---
+
+## What You'll Build
+
+Your users click "Login" in your app, their browser opens, they log in, and they're back in your app - authenticated and ready to go. Tokens are stored securely on their device.
+
+---
+
+## Quick Start
+
+### 1. Get Your Config File
+
+Download `tidecloak.json` (your client adapter config) from your TideCloak admin console. It has all your TideCloak settings.
+
+### 2. Create Your Adapter
+
+The adapter handles platform-specific stuff - opening login windows, storing tokens. Here's one for Electron:
+
+```js
+// electronAdapter.js
+export function createElectronAdapter() {
+  return {
+    // Where should TideCloak redirect after login?
+    getRedirectUri: () => 'myapp://auth/callback',
+
+    // Open login in a popup window (NOT external browser - see note below)
+    openExternalUrl: async (url) => {
+      await window.ipcRenderer.invoke('open-auth-popup', url);
+    },
+
+    // Listen for the auth callback
+    onAuthCallback: (callback) => {
+      const handler = (_event, data) => callback(data);
+      window.ipcRenderer.on('auth-callback', handler);
+      return () => window.ipcRenderer.off('auth-callback', handler);
+    },
+
+    // Store tokens securely
+    saveTokens: async (tokens) => {
+      await window.ipcRenderer.invoke('save-tokens', tokens);
+      return true;
+    },
+
+    // Get stored tokens
+    getTokens: async () => {
+      return await window.ipcRenderer.invoke('get-tokens');
+    },
+
+    // Clear tokens on logout
+    deleteTokens: async () => {
+      await window.ipcRenderer.invoke('delete-tokens');
+      return true;
+    },
+  };
+}
+```
+
+That's it for the adapter. Just 6 functions, all platform-specific. The SDK handles everything else.
+
+> **Popup Window vs External Browser**
+>
+> If you need **encryption/decryption**, you **must** use a popup window (Electron BrowserWindow) instead of the system's external browser. This keeps session cookies inside your Electron app, which is required for the encryption/decryption session key to work.
+>
+> | Approach | Session Cookies | Encryption/Decryption |
+> |----------|-----------------|------------|
+> | Popup window (BrowserWindow) | Stays in Electron | Works |
+> | External browser (shell.openExternal) | Separate from Electron | Fails with "session key mismatch" |
+>
+> Without the session cookies, `doEncrypt()` and `doDecrypt()` will fail.
+>
+> Your main process should create a BrowserWindow for login, not call `shell.openExternal()`.
+
+### 3. Initialize the SDK
+
+```js
+import { IAMService } from "@tidecloak/js";
+import adapterConfig from "./tidecloak.json";
+import { createElectronAdapter } from "./electronAdapter";
+
+const config = {
+  authMode: "native",
+  adapter: createElectronAdapter(),
+  ...adapterConfig,  // Spread your tidecloak.json config
+};
+
+// Listen for events. Handlers get the event name first, then its arguments.
+IAMService
+  .on("authSuccess", () => console.log("Logged in!"))
+  .on("authError", (_event, err) => console.error("Login failed:", err))
+  .on("logout", () => console.log("Logged out"));
+
+// Start the SDK
+await IAMService.initIAM(config);
+```
+
+### Session Mode
+
+Control how the SDK handles tokens on startup:
+
+```js
+const config = {
+  authMode: "native",
+  adapter: createElectronAdapter(),
+  sessionMode: "offline",  // or "online"
+  ...adapterConfig,
+};
+```
+
+| Mode | Behavior | Best For |
+|------|----------|----------|
+| `"online"` | Validates tokens with server, refreshes if needed, requires login if invalid | Always-connected apps |
+| `"offline"` | Accepts stored tokens without server validation, even if expired | Offline-first apps |
+
+**Offline mode** is great for apps that need to work without internet. Users can access the app with expired tokens, and you only prompt for re-login when an API call fails with 401.
+
+### 4. Login and Logout
+
+```js
+// Login - opens system browser
+IAMService.doLogin();
+
+// Logout - clears tokens
+IAMService.doLogout();
+
+// Check login state
+if (IAMService.isLoggedIn()) {
+  console.log("User is logged in");
+}
+```
+
+---
+
+## Everything You Can Do
+
+```js
+// Check auth state
+IAMService.isLoggedIn();          // Is user logged in?
+
+// Get tokens
+await IAMService.getToken();      // Access token
+IAMService.getIDToken();          // ID token
+
+// Get user info
+IAMService.getName();             // Username
+IAMService.getValueFromToken("email");
+IAMService.getValueFromIDToken("name"); // getValueFromIdToken also works
+
+// Check roles
+IAMService.hasRealmRole("admin");
+IAMService.hasClientRole("editor");
+
+// Auth actions
+IAMService.doLogin();
+IAMService.doLogout();
+await IAMService.updateIAMToken();  // Refresh token
+
+// Encryption (if configured)
+await IAMService.doEncrypt([{ data: "secret", tags: ["personal"] }]);
+await IAMService.doDecrypt([{ encrypted: "...", tags: ["personal"] }]);
+```
+
+---
+
+## Events
+
+Know when things happen:
+
+```js
+IAMService
+  .on("authSuccess", () => {
+    // User logged in successfully
+  })
+  .on("authError", (_event, err) => {
+    // Login failed
+  })
+  .on("logout", () => {
+    // User logged out
+  })
+  .on("tokenExpired", () => {
+    // Token expired - SDK will try to refresh
+  });
+```
+
+---
+
+## Encryption
+
+If your TideCloak is set up for encryption, you can protect sensitive data:
+
+```js
+// Encrypt
+const [encrypted] = await IAMService.doEncrypt([
+  { data: "sensitive info", tags: ["personal"] }
+]);
+
+// Decrypt
+const [decrypted] = await IAMService.doDecrypt([
+  { encrypted, tags: ["personal"] }
+]);
+```
+
+Users need the right roles (`_tide_<tag>.selfencrypt` / `_tide_<tag>.selfdecrypt`) to encrypt/decrypt with specific tags.
+
+Native mode doesn't support decryption policies. Passing a policy to `doEncrypt` or `doDecrypt` throws, and the draft/commit encryption methods aren't available.
+
+---
+
+## Platform Setup
+
+### Electron
+
+You'll need to set up your main process to:
+
+1. **Create a popup window for login** (required for encryption):
+```js
+// main.js
+ipcMain.handle('open-auth-popup', async (event, url) => {
+  const authWindow = new BrowserWindow({
+    width: 500,
+    height: 700,
+    webPreferences: {
+      nodeIntegration: false,
+      contextIsolation: true,
+    },
+  });
+
+  // Listen for redirect
+  authWindow.webContents.on('will-redirect', (event, redirectUrl) => {
+    if (redirectUrl.startsWith('myapp://')) {
+      const url = new URL(redirectUrl);
+      const code = url.searchParams.get('code');
+      const error = url.searchParams.get('error');
+
+      // Send back to renderer
+      mainWindow.webContents.send('auth-callback', { code, error });
+      authWindow.close();
+    }
+  });
+
+  authWindow.loadURL(url);
+});
+```
+
+2. **Register a custom protocol** (e.g., `myapp://`)
+
+3. **Store tokens securely** (use `safeStorage` or similar)
+
+4. **Handle token storage IPC calls**
+
+### Tauri
+
+Similar to Electron - use a WebView window for login, register a protocol and handle callbacks.
+
+### React Native
+
+Use deep links for the callback URL and secure storage for tokens.
+
+---
+
+## Troubleshooting
+
+**Login opens but nothing happens after**
+
+Make sure your redirect URI is registered in TideCloak and your app is handling the callback.
+
+**Tokens not persisting**
+
+Check that your `saveTokens` and `getTokens` functions are working correctly.
+
+**Encryption/decryption fails with "session key mismatch"**
+
+You're probably using an external browser instead of a popup window. The session cookies from login must stay in your Electron app for encryption/decryption to work.
+
+Fix: Use `new BrowserWindow()` to open the login page, not `shell.openExternal()`.
+
+**Encryption/decryption fails with missing config**
+
+Make sure your `tidecloak.json` includes:
+- `vendorId` - Your Tide vendor ID
+- `client-origin-auth-{origin}` - Auth signature for your app's origin (e.g., `client-origin-auth-http://localhost:5174`)