@tidecloak/js 0.14.33-staging → 0.14.34-staging

package/dist/types/src/utils/dpopAuthPage.d.ts

@@ -0,0 +1,22 @@
+export declare function utf8ToHex(value: any): string;
+export declare function buildDpopAuthUrl({ origin, authServerUrl, realm, clientId }: {
+    authServerUrl: any;
+    clientId: any;
+    origin: any;
+    realm: any;
+}): string | null;
+export declare function probeDpopAuthPage({ url, fetchImpl, timeoutMs }: {
+    fetchImpl?: typeof fetch | undefined;
+    timeoutMs?: number | undefined;
+    url: any;
+}): Promise<{
+    outcome: string;
+    missing?: undefined;
+} | {
+    outcome: string;
+    missing: string[];
+}>;
+export declare function preflightDpopAuthPage({ logger, ...params }: {
+    [x: string]: any;
+    logger?: Console | undefined;
+}): Promise<string>;

package/dist/types/src/utils/index.d.ts

@@ -2,3 +2,4 @@ export { makePkce, randomPkceVerifier, base64UrlEncode } from './pkce.js';
 export { fetchJson } from './fetch.js';
 export { resolveSilentCheckSsoRedirectUri, SILENT_CHECK_SSO_FILENAME } from './silentCheckSso.js';
 export { buildInitOptions } from './initOptions.js';
+export { preflightDpopAuthPage } from './dpopAuthPage.js';

package/dist/types/src/vite.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @param {Object} [options]
+ * @param {Object} [options.config] TideCloak adapter config (tidecloak.json). Used to
+ *   reject requests for another realm or client.
+ */
+export declare function tideDpopPlugin({ config }?: {
+    config?: Object;
+}): {
+    name: string;
+    configureServer: (server: any) => void;
+    configurePreviewServer: (server: any) => void;
+};
+export default tideDpopPlugin;

package/dist/types/utils/dpopAuthPage.d.ts

@@ -0,0 +1,22 @@
+export declare function utf8ToHex(value: any): string;
+export declare function buildDpopAuthUrl({ origin, authServerUrl, realm, clientId }: {
+    authServerUrl: any;
+    clientId: any;
+    origin: any;
+    realm: any;
+}): string | null;
+export declare function probeDpopAuthPage({ url, fetchImpl, timeoutMs }: {
+    fetchImpl?: typeof fetch | undefined;
+    timeoutMs?: number | undefined;
+    url: any;
+}): Promise<{
+    outcome: string;
+    missing?: undefined;
+} | {
+    outcome: string;
+    missing: string[];
+}>;
+export declare function preflightDpopAuthPage({ logger, ...params }: {
+    [x: string]: any;
+    logger?: Console | undefined;
+}): Promise<string>;

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

@@ -2,3 +2,4 @@ export { makePkce, randomPkceVerifier, base64UrlEncode } from './pkce.js';
 export { fetchJson } from './fetch.js';
 export { resolveSilentCheckSsoRedirectUri, SILENT_CHECK_SSO_FILENAME } from './silentCheckSso.js';
 export { buildInitOptions } from './initOptions.js';
+export { preflightDpopAuthPage } from './dpopAuthPage.js';

package/dist/types/vite.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @param {Object} [options]
+ * @param {Object} [options.config] TideCloak adapter config (tidecloak.json). Used to
+ *   reject requests for another realm or client.
+ */
+export declare function tideDpopPlugin({ config }?: {
+    config?: Object;
+}): {
+    name: string;
+    configureServer: (server: any) => void;
+    configurePreviewServer: (server: any) => void;
+};
+export default tideDpopPlugin;

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.