@iqauth/sdk 2.5.0 → 2.6.1

package/README.md

@@ -17,6 +17,7 @@ The canonical TypeScript SDK for **IQAuthService** — DispositionIQ's multi-ten
 - [Install](#install)
 - [Five-line integration](#five-line-integration)
 - [Pick your environment](#pick-your-environment)
+- [What's new in 2.6.1](#whats-new-in-261)
 - [What's new in 2.0.3](#whats-new-in-203)
 - [Browser apps with a backend (recommended)](#browser-apps-with-a-backend-recommended)
 - [Server reference (Express, Fastify, Hono, Next.js)](#server-reference)
@@ -89,6 +90,13 @@ gap, mirroring Clerk's `<ClerkLoading/>` / `<ClerkLoaded/>`.
 Available hooks: `useUser()`, `useSession()`, `useAuth()`, `useOrganization()`. Each returns `{ data, isLoading, error }`.
 Drop-in components: `<SignIn/>`, `<SignUp/>`, `<UserButton/>`, `<UserProfile/>`, `<OrganizationSwitcher/>`, `<AuthCallback/>`.
 
+> **Silent SSO is opt-in as of 2.6.1.** `<SignIn/>` always renders the
+> form on first paint by default — even for returning users with an active
+> issuer-side `iq_sso` session. To restore the old auto-resume behavior,
+> add `silentSso` to the provider or a specific `<SignIn/>` instance:
+> `<IQAuthProvider publishableKey={…} silentSso>` or `<SignIn silentSso />`.
+> See "What's new in 2.6.1" below.
+
 ### Express
 
 ```ts
@@ -165,6 +173,55 @@ The SDK is not "one auth model for every environment". The safe pattern depends
 
 ---
 
+## What's new in 2.6.1
+
+### 1. Silent SSO is now opt-in (default off)
+
+Previously, `<SignIn/>` would detect an active issuer-side `iq_sso` session
+on mount and silently redirect through `/oidc/sso-resume` — users never saw
+the form, never clicked anything, and were transparently signed back in.
+That was surprising for embedded use cases and made it impossible to switch
+accounts without reaching for `?prompt=login`. As of 2.6.1, silent SSO is
+**disabled by default** and must be explicitly enabled:
+
+```tsx
+// Provider-wide opt-in (covers every <SignIn/> below it)
+<IQAuthProvider publishableKey={…} silentSso>
+  …
+</IQAuthProvider>
+
+// Per-instance opt-in (overrides the provider value)
+<SignIn silentSso />
+```
+
+When silent SSO is off (default), `<SignIn/>` always renders the form on
+first paint regardless of `iq_sso` cookie state. `prompt="login"` and
+`?prompt=login` continue to work as additional force-form switches.
+
+### 2. Embedded card no longer forces full-viewport height
+
+The internal `.iqauth-sdk-pane` declared `min-height: 100vh` unconditionally,
+which worked for hosted full-page sign-in but broke when `<SignIn/>` was
+embedded in a card, modal, or sidebar — pushing content below the fold and
+creating large empty areas. The 100vh height now applies only inside the
+wide side-by-side layout (`@container iqauth-sdk (min-width: 768px)`) where
+the hero pane needs height parity. Narrow embeds size naturally to their
+content.
+
+### 3. Better error reporting on misconfigured `<SignIn/>`
+
+- `useIQAuthSignInContext` now detects HTML responses (CORS preflight, wrong
+  `iqAuthBaseUrl`, wrong `appKey`) and prints an actionable `console.error`
+  naming the three likely causes — instead of the cryptic
+  `Unexpected token '<' in JSON`.
+- The "returnTo not in allowed origins" console error now also lists the
+  app's actual `allowedOrigins`, so the diff with the rejected `returnTo`
+  is visible at a glance instead of requiring a Network-tab spelunk.
+
+For older versions see [`CHANGELOG.md`](./CHANGELOG.md).
+
+---
+
 ## What's new in 2.0.3
 
 ### 1. `serverManagedSession: true` for `SessionManager` / `IQAuthProvider`

package/dist/react.d.mts

@@ -116,6 +116,13 @@ interface IQAuthContextValue {
     roleMapper: ((claims: JwtClaims | null) => string | null) | null;
     /** Task #95 — fully resolved localization bundle (default + override). */
     localization: IQAuthLocaleBundle;
+    /**
+     * 2.6.1 — Whether `<SignIn/>` is allowed to silently resume an active SSO
+     * session and redirect the user without showing the form. Opt-in. Default
+     * `false` so consumers always see the sign-in UI on first paint unless they
+     * explicitly enable it. Per-instance `<SignIn silentSso>` overrides this.
+     */
+    silentSso: boolean;
 }
 interface IQAuthProviderProps {
     publishableKey: string;
@@ -154,6 +161,14 @@ interface IQAuthProviderProps {
      * default `enUS` strings.
      */
     localization?: IQAuthLocaleBundle | IQAuthLocaleOverride;
+    /**
+     * 2.6.1 — Opt into silent SSO resume in `<SignIn/>` (default `false`).
+     * When `true`, `<SignIn/>` will detect an active issuer-side `iq_sso`
+     * session and redirect through `/oidc/sso-resume` without rendering the
+     * form. When `false` (default) the form always renders and users must
+     * click to continue. Per-instance `<SignIn silentSso>` overrides this.
+     */
+    silentSso?: boolean;
     children?: ReactNode;
 }
 /**
@@ -162,7 +177,7 @@ interface IQAuthProviderProps {
  * safe — a single SessionManager instance is created per provider and reused
  * across remounts.
  */
-declare function IQAuthProvider({ publishableKey, issuer, channelName, proactiveRefresh, manager: externalManager, allowedReturnOrigins, appearance, roleMapper, cookieNames, localization, children, }: IQAuthProviderProps): React.FunctionComponentElement<React.ProviderProps<IQAuthContextValue | null>>;
+declare function IQAuthProvider({ publishableKey, issuer, channelName, proactiveRefresh, manager: externalManager, allowedReturnOrigins, appearance, roleMapper, cookieNames, localization, silentSso, children, }: IQAuthProviderProps): React.FunctionComponentElement<React.ProviderProps<IQAuthContextValue | null>>;
 /**
  * Task #95 — Returns the active localization bundle resolved from the
  * `localization` prop on `<IQAuthProvider>` (merged on top of `enUS`). Safe
@@ -578,6 +593,13 @@ interface SignInProps extends Partial<SharedComponentProps> {
     prompt?: "login";
     /** F11 — Per-instance appearance overrides; merged on top of provider-level appearance. */
     appearance?: IQAuthAppearance;
+    /**
+     * 2.6.1 — Per-instance opt-in to silent SSO resume. Overrides the
+     * `<IQAuthProvider silentSso>` value when supplied. Default (when both are
+     * unset): `false` — the form always renders and the user must click to
+     * continue.
+     */
+    silentSso?: boolean;
 }
 /**
  * Pure render-decision helper. When this returns `true`, `<SignIn/>` MUST

package/dist/react.d.ts

@@ -116,6 +116,13 @@ interface IQAuthContextValue {
     roleMapper: ((claims: JwtClaims | null) => string | null) | null;
     /** Task #95 — fully resolved localization bundle (default + override). */
     localization: IQAuthLocaleBundle;
+    /**
+     * 2.6.1 — Whether `<SignIn/>` is allowed to silently resume an active SSO
+     * session and redirect the user without showing the form. Opt-in. Default
+     * `false` so consumers always see the sign-in UI on first paint unless they
+     * explicitly enable it. Per-instance `<SignIn silentSso>` overrides this.
+     */
+    silentSso: boolean;
 }
 interface IQAuthProviderProps {
     publishableKey: string;
@@ -154,6 +161,14 @@ interface IQAuthProviderProps {
      * default `enUS` strings.
      */
     localization?: IQAuthLocaleBundle | IQAuthLocaleOverride;
+    /**
+     * 2.6.1 — Opt into silent SSO resume in `<SignIn/>` (default `false`).
+     * When `true`, `<SignIn/>` will detect an active issuer-side `iq_sso`
+     * session and redirect through `/oidc/sso-resume` without rendering the
+     * form. When `false` (default) the form always renders and users must
+     * click to continue. Per-instance `<SignIn silentSso>` overrides this.
+     */
+    silentSso?: boolean;
     children?: ReactNode;
 }
 /**
@@ -162,7 +177,7 @@ interface IQAuthProviderProps {
  * safe — a single SessionManager instance is created per provider and reused
  * across remounts.
  */
-declare function IQAuthProvider({ publishableKey, issuer, channelName, proactiveRefresh, manager: externalManager, allowedReturnOrigins, appearance, roleMapper, cookieNames, localization, children, }: IQAuthProviderProps): React.FunctionComponentElement<React.ProviderProps<IQAuthContextValue | null>>;
+declare function IQAuthProvider({ publishableKey, issuer, channelName, proactiveRefresh, manager: externalManager, allowedReturnOrigins, appearance, roleMapper, cookieNames, localization, silentSso, children, }: IQAuthProviderProps): React.FunctionComponentElement<React.ProviderProps<IQAuthContextValue | null>>;
 /**
  * Task #95 — Returns the active localization bundle resolved from the
  * `localization` prop on `<IQAuthProvider>` (merged on top of `enUS`). Safe
@@ -578,6 +593,13 @@ interface SignInProps extends Partial<SharedComponentProps> {
     prompt?: "login";
     /** F11 — Per-instance appearance overrides; merged on top of provider-level appearance. */
     appearance?: IQAuthAppearance;
+    /**
+     * 2.6.1 — Per-instance opt-in to silent SSO resume. Overrides the
+     * `<IQAuthProvider silentSso>` value when supplied. Default (when both are
+     * unset): `false` — the form always renders and the user must click to
+     * continue.
+     */
+    silentSso?: boolean;
 }
 /**
  * Pure render-decision helper. When this returns `true`, `<SignIn/>` MUST

package/dist/react.js

@@ -1847,6 +1847,7 @@ function IQAuthProvider({
   roleMapper,
   cookieNames,
   localization,
+  silentSso,
   children
 }) {
   const managerRef = (0, import_react.useRef)(null);
@@ -1895,9 +1896,10 @@ function IQAuthProvider({
       allowedReturnOrigins: allowedReturnOrigins ?? [],
       appearance: appearance ?? null,
       roleMapper: roleMapper ?? null,
-      localization: resolvedLocalization
+      localization: resolvedLocalization,
+      silentSso: silentSso ?? false
     }),
-    [manager, snapshot, allowedReturnOrigins, appearance, roleMapper, resolvedLocalization]
+    [manager, snapshot, allowedReturnOrigins, appearance, roleMapper, resolvedLocalization, silentSso]
   );
   return (0, import_react.createElement)(IQAuthContext.Provider, { value }, children);
 }
@@ -2374,7 +2376,19 @@ function useIQAuthSignInContext(iqAuthBaseUrl, appKey, returnTo) {
     let cancelled = false;
     setLoading(true);
     const url2 = `${iqAuthBaseUrl.replace(/\/$/, "")}/api/public/apps/${encodeURIComponent(appKey)}/sign-in-context?return_to=${encodeURIComponent(returnTo)}`;
-    fetch(url2, { credentials: "include" }).then((r) => r.json()).then((payload) => {
+    fetch(url2, { credentials: "include" }).then(async (r) => {
+      const contentType = r.headers.get("content-type") || "";
+      if (!r.ok || !contentType.includes("json")) {
+        const bodyPreview = await r.text().then((t2) => t2.slice(0, 160)).catch(() => "");
+        console.error(
+          `[IQAuth] sign-in-context request failed: ${r.status} ${r.statusText} (content-type: ${contentType || "\u2014"}). URL: ${url2}. Common causes: (1) iqAuthBaseUrl points at the wrong host (it should be your IQAuth issuer, e.g. https://auth.dispositioniq.com \u2014 NOT your own app's domain); (2) the app key "${appKey}" is wrong or revoked; (3) CORS preflight is blocked because this origin isn't in the app's allowed-origins list. Response body preview: ${bodyPreview}`
+        );
+        throw new Error(
+          r.status >= 500 ? "Failed to load sign-in context (server error)" : `Failed to load sign-in context (HTTP ${r.status})`
+        );
+      }
+      return r.json();
+    }).then((payload) => {
       if (cancelled) return;
       if (payload?.success === false) throw new Error(payload?.error?.message || "Failed to load sign-in context");
       setCtx(payload.data);
@@ -2397,11 +2411,25 @@ var SHELL_CSS = `
   grid-template-columns: 1fr;
   background: var(--brand-bg, #f7f7f6);
   color: var(--brand-text, #0f172a);
+  /* Container queries so the two-pane layout responds to the SDK's
+     RENDERED width, not the viewport. This keeps the form usable when
+     a host app embeds <SignIn/> inside a narrower card or sidebar
+     instead of full-screen \u2014 the previous viewport @media query would
+     happily render the side-by-side hero+form into a 200px container
+     and wrap text one character per line. */
+  container-type: inline-size;
+  container-name: iqauth-sdk;
 }
 .iqauth-sdk-hero { display: none; }
 .iqauth-sdk-pane {
   display: flex; flex-direction: column; align-items: center; justify-content: center;
-  padding: 48px 24px; min-height: 100vh;
+  padding: 32px 20px;
+  /* 2.6.1 \u2014 Default to natural height so embedded usage (inside a card,
+     modal, or sidebar) sizes to its content instead of forcing a full
+     viewport. The hosted/full-page layout re-introduces 100vh below the
+     768px container-query threshold for the side-by-side hero variant. */
+  min-height: auto;
+  box-sizing: border-box;
 }
 .iqauth-sdk-card {
   width: 100%; max-width: 460px;
@@ -2446,8 +2474,11 @@ var SHELL_CSS = `
 .iqauth-sdk-google-btn:hover { background: #f8fafc; border-color: rgba(15,23,42,0.28); }
 .iqauth-sdk-google-btn[disabled] { opacity: 0.6; cursor: not-allowed; }
 
-@media (min-width: 768px) {
+@container iqauth-sdk (min-width: 768px) {
   .iqauth-sdk-shell:not([data-layout="centered_card"]):not([data-layout="full_bleed"]) { grid-template-columns: minmax(0, 1fr) minmax(0, 1fr); }
+  /* 2.6.1 \u2014 Restore 100vh ONLY for the wide side-by-side layout where
+     hero+pane need height parity. Embedded narrow uses keep natural height. */
+  .iqauth-sdk-pane { padding: 48px 24px; min-height: 100vh; }
   .iqauth-sdk-hero {
     display: flex; flex-direction: column; justify-content: space-between;
     padding: clamp(32px, 4vw, 56px); color: #ffffff;
@@ -2467,7 +2498,7 @@ var SHELL_CSS = `
   .iqauth-sdk-hero-foot { font-size: 12px; opacity: 0.7; }
   .iqauth-sdk-mobile-brand { display: none; }
 }
-@media (min-width: 1280px) {
+@container iqauth-sdk (min-width: 1280px) {
   .iqauth-sdk-shell:not([data-layout="centered_card"]):not([data-layout="full_bleed"]) { grid-template-columns: minmax(0, 5fr) minmax(0, 6fr); }
 }
 `;
@@ -2773,7 +2804,8 @@ function SignIn(props) {
   const iqAuthBaseUrl = props.iqAuthBaseUrl ?? providerCtx?.manager.issuerUrl ?? "";
   const appKey = props.appKey ?? providerCtx?.manager.appKey ?? "";
   const returnTo = props.returnTo ?? (typeof window !== "undefined" ? `${window.location.origin}/api/iqauth/callback` : "");
-  const { onRedirect, className, prompt, appearance: instanceAppearance } = props;
+  const { onRedirect, className, prompt, appearance: instanceAppearance, silentSso: instanceSilentSso } = props;
+  const silentSsoEnabled = instanceSilentSso ?? providerCtx?.silentSso ?? false;
   const appearance = instanceAppearance && providerCtx?.appearance ? { elements: { ...providerCtx.appearance.elements, ...instanceAppearance.elements } } : instanceAppearance ?? providerCtx?.appearance ?? null;
   if (!iqAuthBaseUrl || !appKey) {
     console.error(
@@ -2803,6 +2835,7 @@ function SignIn(props) {
   const [forcePrompt, setForcePrompt] = (0, import_react.useState)(false);
   const effectivePrompt = (0, import_react.useMemo)(() => {
     if (prompt === "login" || forcePrompt) return "login";
+    if (!silentSsoEnabled) return "login";
     if (typeof window !== "undefined") {
       try {
         if (new URLSearchParams(window.location.search).get("prompt") === "login") return "login";
@@ -2810,7 +2843,7 @@ function SignIn(props) {
       }
     }
     return void 0;
-  }, [prompt, forcePrompt]);
+  }, [prompt, forcePrompt, silentSsoEnabled]);
   const oidcPayload = () => ({
     client_id: ctx?.app.defaultClientId,
     redirect_uri: returnTo,

package/dist/react.mjs

@@ -102,6 +102,7 @@ function IQAuthProvider({
   roleMapper,
   cookieNames,
   localization,
+  silentSso,
   children
 }) {
   const managerRef = useRef(null);
@@ -150,9 +151,10 @@ function IQAuthProvider({
       allowedReturnOrigins: allowedReturnOrigins ?? [],
       appearance: appearance ?? null,
       roleMapper: roleMapper ?? null,
-      localization: resolvedLocalization
+      localization: resolvedLocalization,
+      silentSso: silentSso ?? false
     }),
-    [manager, snapshot, allowedReturnOrigins, appearance, roleMapper, resolvedLocalization]
+    [manager, snapshot, allowedReturnOrigins, appearance, roleMapper, resolvedLocalization, silentSso]
   );
   return createElement(IQAuthContext.Provider, { value }, children);
 }
@@ -629,7 +631,19 @@ function useIQAuthSignInContext(iqAuthBaseUrl, appKey, returnTo) {
     let cancelled = false;
     setLoading(true);
     const url = `${iqAuthBaseUrl.replace(/\/$/, "")}/api/public/apps/${encodeURIComponent(appKey)}/sign-in-context?return_to=${encodeURIComponent(returnTo)}`;
-    fetch(url, { credentials: "include" }).then((r) => r.json()).then((payload) => {
+    fetch(url, { credentials: "include" }).then(async (r) => {
+      const contentType = r.headers.get("content-type") || "";
+      if (!r.ok || !contentType.includes("json")) {
+        const bodyPreview = await r.text().then((t2) => t2.slice(0, 160)).catch(() => "");
+        console.error(
+          `[IQAuth] sign-in-context request failed: ${r.status} ${r.statusText} (content-type: ${contentType || "\u2014"}). URL: ${url}. Common causes: (1) iqAuthBaseUrl points at the wrong host (it should be your IQAuth issuer, e.g. https://auth.dispositioniq.com \u2014 NOT your own app's domain); (2) the app key "${appKey}" is wrong or revoked; (3) CORS preflight is blocked because this origin isn't in the app's allowed-origins list. Response body preview: ${bodyPreview}`
+        );
+        throw new Error(
+          r.status >= 500 ? "Failed to load sign-in context (server error)" : `Failed to load sign-in context (HTTP ${r.status})`
+        );
+      }
+      return r.json();
+    }).then((payload) => {
       if (cancelled) return;
       if (payload?.success === false) throw new Error(payload?.error?.message || "Failed to load sign-in context");
       setCtx(payload.data);
@@ -652,11 +666,25 @@ var SHELL_CSS = `
   grid-template-columns: 1fr;
   background: var(--brand-bg, #f7f7f6);
   color: var(--brand-text, #0f172a);
+  /* Container queries so the two-pane layout responds to the SDK's
+     RENDERED width, not the viewport. This keeps the form usable when
+     a host app embeds <SignIn/> inside a narrower card or sidebar
+     instead of full-screen \u2014 the previous viewport @media query would
+     happily render the side-by-side hero+form into a 200px container
+     and wrap text one character per line. */
+  container-type: inline-size;
+  container-name: iqauth-sdk;
 }
 .iqauth-sdk-hero { display: none; }
 .iqauth-sdk-pane {
   display: flex; flex-direction: column; align-items: center; justify-content: center;
-  padding: 48px 24px; min-height: 100vh;
+  padding: 32px 20px;
+  /* 2.6.1 \u2014 Default to natural height so embedded usage (inside a card,
+     modal, or sidebar) sizes to its content instead of forcing a full
+     viewport. The hosted/full-page layout re-introduces 100vh below the
+     768px container-query threshold for the side-by-side hero variant. */
+  min-height: auto;
+  box-sizing: border-box;
 }
 .iqauth-sdk-card {
   width: 100%; max-width: 460px;
@@ -701,8 +729,11 @@ var SHELL_CSS = `
 .iqauth-sdk-google-btn:hover { background: #f8fafc; border-color: rgba(15,23,42,0.28); }
 .iqauth-sdk-google-btn[disabled] { opacity: 0.6; cursor: not-allowed; }
 
-@media (min-width: 768px) {
+@container iqauth-sdk (min-width: 768px) {
   .iqauth-sdk-shell:not([data-layout="centered_card"]):not([data-layout="full_bleed"]) { grid-template-columns: minmax(0, 1fr) minmax(0, 1fr); }
+  /* 2.6.1 \u2014 Restore 100vh ONLY for the wide side-by-side layout where
+     hero+pane need height parity. Embedded narrow uses keep natural height. */
+  .iqauth-sdk-pane { padding: 48px 24px; min-height: 100vh; }
   .iqauth-sdk-hero {
     display: flex; flex-direction: column; justify-content: space-between;
     padding: clamp(32px, 4vw, 56px); color: #ffffff;
@@ -722,7 +753,7 @@ var SHELL_CSS = `
   .iqauth-sdk-hero-foot { font-size: 12px; opacity: 0.7; }
   .iqauth-sdk-mobile-brand { display: none; }
 }
-@media (min-width: 1280px) {
+@container iqauth-sdk (min-width: 1280px) {
   .iqauth-sdk-shell:not([data-layout="centered_card"]):not([data-layout="full_bleed"]) { grid-template-columns: minmax(0, 5fr) minmax(0, 6fr); }
 }
 `;
@@ -1028,7 +1059,8 @@ function SignIn(props) {
   const iqAuthBaseUrl = props.iqAuthBaseUrl ?? providerCtx?.manager.issuerUrl ?? "";
   const appKey = props.appKey ?? providerCtx?.manager.appKey ?? "";
   const returnTo = props.returnTo ?? (typeof window !== "undefined" ? `${window.location.origin}/api/iqauth/callback` : "");
-  const { onRedirect, className, prompt, appearance: instanceAppearance } = props;
+  const { onRedirect, className, prompt, appearance: instanceAppearance, silentSso: instanceSilentSso } = props;
+  const silentSsoEnabled = instanceSilentSso ?? providerCtx?.silentSso ?? false;
   const appearance = instanceAppearance && providerCtx?.appearance ? { elements: { ...providerCtx.appearance.elements, ...instanceAppearance.elements } } : instanceAppearance ?? providerCtx?.appearance ?? null;
   if (!iqAuthBaseUrl || !appKey) {
     console.error(
@@ -1058,6 +1090,7 @@ function SignIn(props) {
   const [forcePrompt, setForcePrompt] = useState(false);
   const effectivePrompt = useMemo(() => {
     if (prompt === "login" || forcePrompt) return "login";
+    if (!silentSsoEnabled) return "login";
     if (typeof window !== "undefined") {
       try {
         if (new URLSearchParams(window.location.search).get("prompt") === "login") return "login";
@@ -1065,7 +1098,7 @@ function SignIn(props) {
       }
     }
     return void 0;
-  }, [prompt, forcePrompt]);
+  }, [prompt, forcePrompt, silentSsoEnabled]);
   const oidcPayload = () => ({
     client_id: ctx?.app.defaultClientId,
     redirect_uri: returnTo,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iqauth/sdk",
-  "version": "2.5.0",
+  "version": "2.6.1",
   "description": "TypeScript SDK for IQAuth — the canonical way for all IQ projects to integrate with IQAuthService",
   "main": "dist/index.js",
   "module": "dist/index.mjs",