@tidecloak/js 0.14.41-staging → 0.14.42-staging

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

@@ -1,22 +0,0 @@
-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/fetch.d.ts

@@ -1,11 +0,0 @@
-/**
- * Fetch utilities for HTTP requests.
- */
-/**
- * Fetch JSON with credentials included.
- * @param {string} url - URL to fetch
- * @param {RequestInit} [options={}] - Fetch options
- * @returns {Promise<any>} Parsed JSON response
- * @throws {Error} If request fails (with status and body properties)
- */
-export declare function fetchJson(url: string, options?: RequestInit): Promise<any>;

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

@@ -1,5 +0,0 @@
-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/utils/initOptions.d.ts

@@ -1,69 +0,0 @@
-/**
- * Builds the options object handed to `TideCloak.init()` from a caller's
- * resolved TideCloak config.
- *
- * ## Why this is an ALLOWLIST, deliberately
- *
- * `IAMService.initIAM` has always built these options as an allowlist: it reads
- * a handful of keys off the config and drops everything else on the floor. The
- * config object is NOT a `KeycloakInitOptions` bag - it is an adapter/config
- * snapshot (`tidecloak.json` + Tide fields + app-level OIDC hints), and callers
- * legitimately put keys in it that are meaningful to `IAMService` (or to their
- * own code) but that must NOT be handed to `init()`.
- *
- * PR #91 widened this allowlist to also forward `redirectUri`,
- * `silentCheckSsoFallback`, `silentCheckSsoTimeout`, `scope` and a
- * caller-supplied `pkceMethod`, on the reasoning that "each is inert unless the
- * caller sets it". That reasoning is wrong in one important direction: consumers
- * had been shipping configs with these keys set for as long as the keys were
- * being SWALLOWED, so their behaviour was pinned to the SDK's defaults, not to
- * the value in their config. Forwarding them is therefore a silent behaviour
- * change for every existing consumer - the exact opposite of inert.
- *
- * `scope` is the sharpest edge: forwarding it rewrites the authorization
- * request's scope, which changes the audience/roles on the issued access token
- * and can strip a consumer's admin-API access.
- *
- * So: forward ONLY what the SDK genuinely needs, and keep the previously
- * defaulted behaviour byte-for-byte. Any option that a consumer should be able
- * to set must be added here CONSCIOUSLY, with its prior default preserved.
- *
- * ### Forwarded
- * - `setupRequestEnclave` - passed through from the `initIAM` argument.
- * - `onLoad` - always `"check-sso"`. NOT taken from config: callers (e.g. the
- *   admin console) set `onLoad: "login-required"`, and honouring it would send
- *   `#processInit` down the full-redirect branch and never run silent check-sso
- *   at all. That is a separate product decision.
- * - `silentCheckSsoRedirectUri` - the resolved URI (see ./silentCheckSso.js).
- *   This is the ONE option PR #91 needed to make caller-supplied, and it stays.
- *   `undefined` => TideCloak skips silent check-sso and falls back to an
- *   interactive login rather than emitting a URI that would 400.
- * - `pkceMethod` - always `"S256"`, as it was before PR #91.
- * - `useDPoP` / `checkLoginIframe` - the two options `initIAM` has always
- *   forwarded. `useDPoP` is forwarded ONLY when the caller actually set it, and
- *   VERBATIM. DPoP is opt-in: nothing upstream may default it on, because
- *   enabling it appends `dpop_jkt` to the authorization request and the realm
- *   then issues a `cnf.jkt`-BOUND token, which a plain-Bearer consumer cannot
- *   use (RFC 9449) - a bare `401` with no explanation. Pinned in
- *   test/bootstrapDpop.test.js.
- *
- * ### Deliberately NOT forwarded (regression-tested in test/initOptions.test.js)
- * `scope`, `redirectUri`, `silentCheckSsoFallback`, `silentCheckSsoTimeout`.
- * Consumers depend on the SDK's defaults for these. `redirectUri` in particular
- * is still READ from config by `IAMService.doLogin` / `doLogout` and is used as
- * a derivation source for `silentCheckSsoRedirectUri`, so a sub-path-hosted app
- * still gets a correct login redirect - it just does not have `kc.redirectUri`
- * overridden at init time.
- *
- * @param {Object} args
- * @param {Object|null|undefined} args.config Resolved TideCloak config.
- * @param {boolean} args.setupRequestEnclave
- * @param {string|undefined} args.silentCheckSsoRedirectUri Resolved URI, or
- *   `undefined` when no correct URI could be derived.
- * @returns {Object} Options for `TideCloak.init()`.
- */
-export declare function buildInitOptions({ config, setupRequestEnclave, silentCheckSsoRedirectUri, }: {
-    config: Object | null | undefined;
-    setupRequestEnclave: boolean;
-    silentCheckSsoRedirectUri: string | undefined;
-}): Object;

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

@@ -1,24 +0,0 @@
-/**
- * PKCE (Proof Key for Code Exchange) utilities for OAuth 2.0 authorization code flow.
- */
-/**
- * Generate random PKCE verifier string.
- * @param {number} len - Length of the verifier (default 96)
- * @returns {string} Random verifier string
- */
-export declare function randomPkceVerifier(len?: number): string;
-/**
- * Base64 URL encode an ArrayBuffer.
- * @param {ArrayBuffer} arrayBuffer - Buffer to encode
- * @returns {string} Base64 URL encoded string
- */
-export declare function base64UrlEncode(arrayBuffer: ArrayBuffer): string;
-/**
- * Generate PKCE verifier and challenge.
- * @returns {Promise<{verifier: string, challenge: string, method: string}>}
- */
-export declare function makePkce(): Promise<{
-    verifier: string;
-    challenge: string;
-    method: string;
-}>;

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

@@ -1,82 +0,0 @@
-/**
- * Resolution of the silent-check-SSO redirect URI.
- *
- * ## Why this exists
- *
- * `IAMService.initIAM` used to hardcode:
- *
- * ```js
- * silentCheckSsoRedirectUri: `${window.location.origin}/silent-check-sso.html`
- * ```
- *
- * That is only correct for an app served from the ORIGIN ROOT. For any app
- * hosted under a sub-path (e.g. a console served at
- * `https://host/realms/<realm>/tide-console/`) the origin-root URI is:
- *
- *   - NOT served (there is no file at `/silent-check-sso.html`), and
- *   - NOT a registered `redirectUri` on the OIDC client,
- *
- * so the authorization request fails with `400 Invalid parameter: redirect_uri`.
- * The silent iframe then never posts back and the app hangs on its bootstrap
- * spinner. A silently-wrong URI is the worst possible outcome, so this module
- * either derives a CORRECT base-aware URI or reports that it cannot, letting
- * the caller fail loud and fall back to a redirect-based login.
- *
- * ## Resolution order
- *
- * 1. **Caller-supplied `silentCheckSsoRedirectUri`** - always wins, verbatim.
- * 2. **`<base href>`** - the standard way a sub-path-hosted SPA declares where
- *    it lives. Resolved via the browser's own `document.baseURI`.
- * 3. **The app's configured OIDC `redirectUri`** - the SDK already requires this
- *    to be base-aware and registered, so it is a sound source of truth for the
- *    app's base. The SDK's own convention is `<base>auth/redirect`, which is
- *    stripped to recover `<base>` exactly; any other redirect path is resolved
- *    relative to its own directory.
- * 4. **Origin root** - only when the app declares NEITHER a base NOR a
- *    redirectUri. Such an app is relying on the SDK's origin-root default
- *    redirectUri (`${origin}/auth/redirect`) and is therefore root-hosted by
- *    construction. This preserves the historical behaviour for every existing
- *    root-hosted consumer.
- *
- * Anything that cannot be resolved (cross-origin or malformed redirectUri)
- * returns `uri: undefined` plus a `reason`, so the caller can log an error and
- * SKIP the silent check rather than emit a URI that will 400.
- */
-/** Filename the SDK ships and that hosting providers are expected to serve. */
-export declare const SILENT_CHECK_SSO_FILENAME = "silent-check-sso.html";
-export type SilentCheckSsoResolution = {
-    /**
-     * The resolved URI, or undefined if none could be derived.
-     */
-    uri: string | undefined;
-    source: 'config' | 'base-href' | 'redirect-uri-convention' | 'redirect-uri' | 'origin-root' | 'none';
-    /**
-     * Why resolution failed (only when `uri` is undefined).
-     */
-    reason?: string;
-};
-/**
- * @typedef {object} SilentCheckSsoResolution
- * @property {string|undefined} uri    The resolved URI, or undefined if none could be derived.
- * @property {'config'|'base-href'|'redirect-uri-convention'|'redirect-uri'|'origin-root'|'none'} source
- * @property {string} [reason]         Why resolution failed (only when `uri` is undefined).
- */
-/**
- * Resolve the silent-check-SSO redirect URI.
- *
- * Pure: every environment input is passed in explicitly, so this is unit-testable
- * with no DOM. See the module docblock for the resolution order.
- *
- * @param {object} params
- * @param {string} params.origin        The app's origin (`window.location.origin`).
- * @param {string} [params.configured]  Caller-supplied `silentCheckSsoRedirectUri`.
- * @param {string} [params.baseHref]    `document.baseURI`, but ONLY when a `<base href>` element exists.
- * @param {string} [params.redirectUri] Caller-supplied OIDC `redirectUri`.
- * @returns {SilentCheckSsoResolution}
- */
-export declare function resolveSilentCheckSsoRedirectUri({ origin, configured, baseHref, redirectUri }?: {
-    origin: string;
-    configured?: string;
-    baseHref?: string;
-    redirectUri?: string;
-}): SilentCheckSsoResolution;

package/dist/types/vite.d.ts

@@ -1,13 +0,0 @@
-/**
- * @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/HYBRID_MODE.md

@@ -1,185 +0,0 @@
-# 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.