@feelflow/ffid-sdk 5.12.0 → 5.13.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { F as FFIDSubscriptionStatus, a as FFIDConfig, b as FFIDApiResponse, c as FFIDSessionResponse, d as FFIDRedirectResult, e as FFIDError, f as FFIDSubscriptionCheckResponse, g as FFIDCheckServiceAccessParams, h as FFIDServiceAccessDecision, i as FFIDProfileCallOptions, j as FFIDUserProfile, k as FFIDUpdateUserProfileRequest, l as FFIDAnalyticsConfig, m as FFIDVerifyAccessTokenOptions, n as FFIDOAuthUserInfo, o as FFIDInquiryCreateParams, p as FFIDInquiryCreateResponse, q as FFIDAuthMode, r as FFIDLogger, s as FFIDCacheAdapter, t as FFIDUser, u as FFIDOrganization, v as FFIDSubscription, w as FFIDSubscriptionContextValue, E as EffectiveSubscriptionStatus, x as FFIDOAuthUserInfoSubscription, y as FFIDAnnouncementsClientConfig, L as ListAnnouncementsOptions, z as FFIDAnnouncementsApiResponse, A as AnnouncementListResponse, B as FFIDAnnouncementsLogger } from './index-DqsWKU16.cjs';
-export { C as Announcement, D as AnnouncementStatus, G as AnnouncementType, H as EFFECTIVE_SUBSCRIPTION_STATUSES, I as FFIDAnnouncementBadge, J as FFIDAnnouncementList, K as FFIDAnnouncementsError, M as FFIDAnnouncementsErrorCode, N as FFIDAnnouncementsServerResponse, O as FFIDCacheConfig, P as FFIDContextValue, Q as FFIDInquiryCategory, R as FFIDInquiryCategorySite2026, S as FFIDInquiryForm, T as FFIDInquiryFormCategoryItem, U as FFIDInquiryFormClassNames, V as FFIDInquiryFormLegalLayout, W as FFIDInquiryFormOrganization, X as FFIDInquiryFormPlaceholderContext, Y as FFIDInquiryFormPrefill, Z as FFIDInquiryFormProps, _ as FFIDInquiryFormSubmitData, $ as FFIDInquiryFormSubmitResult, a0 as FFIDJwtClaims, a1 as FFIDLoginButton, a2 as FFIDOAuthTokenResponse, a3 as FFIDOAuthUserInfoMemberRole, a4 as FFIDOrganizationSwitcher, a5 as FFIDRedirectErrorCode, a6 as FFIDSeatModel, a7 as FFIDServiceAccessDenialReason, a8 as FFIDServiceAccessFailPolicy, a9 as FFIDSubscriptionBadge, aa as FFIDTokenIntrospectionResponse, ab as FFIDUserMenu, ac as FFID_INQUIRY_CATEGORIES, ad as FFID_INQUIRY_CATEGORIES_SITE_2026, ae as UseFFIDAnnouncementsOptions, af as UseFFIDAnnouncementsReturn, ag as isFFIDInquiryCategorySite2026, ah as useFFIDAnnouncements } from './index-DqsWKU16.cjs';
+import { F as FFIDSubscriptionStatus, a as FFIDConfig, b as FFIDApiResponse, c as FFIDSessionResponse, d as FFIDRedirectResult, e as FFIDError, f as FFIDSubscriptionCheckResponse, g as FFIDCheckServiceAccessParams, h as FFIDServiceAccessDecision, i as FFIDProfileCallOptions, j as FFIDUserProfile, k as FFIDUpdateUserProfileRequest, l as FFIDAnalyticsConfig, m as FFIDVerifyAccessTokenOptions, n as FFIDOAuthUserInfo, o as FFIDInquiryCreateParams, p as FFIDInquiryCreateResponse, q as FFIDAuthMode, r as FFIDLogger, s as FFIDCacheAdapter, t as FFIDUser, u as FFIDOrganization, v as FFIDSubscription, w as FFIDSubscriptionContextValue, E as EffectiveSubscriptionStatus, x as FFIDOAuthUserInfoSubscription, y as FFIDAnnouncementsClientConfig, L as ListAnnouncementsOptions, z as FFIDAnnouncementsApiResponse, A as AnnouncementListResponse, B as FFIDAnnouncementsLogger } from './index-C6dnexXf.cjs';
+export { C as Announcement, D as AnnouncementStatus, G as AnnouncementType, H as EFFECTIVE_SUBSCRIPTION_STATUSES, I as FFIDAnnouncementBadge, J as FFIDAnnouncementList, K as FFIDAnnouncementsError, M as FFIDAnnouncementsErrorCode, N as FFIDAnnouncementsServerResponse, O as FFIDCacheConfig, P as FFIDContextValue, Q as FFIDInquiryCategory, R as FFIDInquiryCategorySite2026, S as FFIDInquiryForm, T as FFIDInquiryFormCategoryItem, U as FFIDInquiryFormClassNames, V as FFIDInquiryFormLegalLayout, W as FFIDInquiryFormOrganization, X as FFIDInquiryFormPlaceholderContext, Y as FFIDInquiryFormPrefill, Z as FFIDInquiryFormProps, _ as FFIDInquiryFormSubmitData, $ as FFIDInquiryFormSubmitResult, a0 as FFIDJwtClaims, a1 as FFIDLoginButton, a2 as FFIDOAuthTokenResponse, a3 as FFIDOAuthUserInfoMemberRole, a4 as FFIDOrganizationSwitcher, a5 as FFIDRedirectErrorCode, a6 as FFIDSeatModel, a7 as FFIDServiceAccessDenialReason, a8 as FFIDServiceAccessFailPolicy, a9 as FFIDSubscriptionBadge, aa as FFIDTokenIntrospectionResponse, ab as FFIDUserMenu, ac as FFID_INQUIRY_CATEGORIES, ad as FFID_INQUIRY_CATEGORIES_SITE_2026, ae as UseFFIDAnnouncementsOptions, af as UseFFIDAnnouncementsReturn, ag as isFFIDInquiryCategorySite2026, ah as useFFIDAnnouncements } from './index-C6dnexXf.cjs';
 export { A as ALL_DENIED_EXCEPT_NECESSARY, i as CONSENT_COOKIE_NAME, j as CONSENT_DISMISSAL_TIMESTAMP_KEY, l as COOKIE_VERSION, D as DEFAULT_CONSENT_ERROR_MESSAGES, o as FFIDAnalyticsProvider, p as FFIDAnalyticsProviderProps, c as FFIDConsentCategories, r as FFIDConsentCategoryCode, e as FFIDConsentCategoryMetadata, w as FFIDConsentError, x as FFIDConsentErrorCode, y as FFIDConsentMergeStrategy, B as FFIDConsentMergeWarning, E as FFIDConsentMergeWarningEvent, F as FFIDConsentResult, I as FFIDConsentSource, a as FFIDConsentState, d as FFIDConsentSyncResult, M as FFIDCookieBanner, N as FFIDCookieBannerClassNames, O as FFIDCookieBannerProps, Q as FFIDCookieLink, R as FFIDCookieLinkProps, f as FFIDCookiePolicy, T as FFIDCookieSettings, U as FFIDCookieSettingsClassNames, V as FFIDCookieSettingsProps, _ as FFID_CONSENT_ERROR_CODES, ae as UseFFIDConsentPreferencesReturn, af as UseFFIDConsentReturn, ag as clearConsentDismissalTimestamp, aj as decodeConsentCookie, al as encodeConsentCookie, an as readConsentCookie, ao as readConsentDismissalTimestamp, aq as useFFIDConsent, ar as useFFIDConsentPreferences, as as writeConsentCookie, at as writeConsentDismissalTimestamp } from './FFIDCookieLink-D1WwE_ZO.cjs';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode, ComponentType, FC } from 'react';
@@ -122,6 +122,35 @@ declare function storeCodeVerifier(verifier: string, logger?: PKCELogger): boole
  */
 declare function retrieveCodeVerifier(logger?: PKCELogger): string | null;
 
+/** Logger interface matching FFIDLogger for optional warning output */
+interface StateLogger {
+    warn: (...args: unknown[]) => void;
+}
+/**
+ * Store the OAuth `state` for later retrieval.
+ *
+ * Writes to both sessionStorage (primary) and localStorage (fallback for iOS
+ * WebKit sessionStorage eviction during external OAuth bounces). Returns true
+ * if at least one write succeeded.
+ *
+ * @param state - The OAuth state value to store
+ * @param logger - Optional logger for warning on storage failure
+ * @returns true if stored in at least one storage, false otherwise
+ */
+declare function storeState(state: string, logger?: StateLogger): boolean;
+/**
+ * Retrieve and remove the OAuth `state`.
+ *
+ * Reads from sessionStorage first, falls back to localStorage (with 5-minute TTL).
+ * Removes from all storages after retrieval (one-time use). Returns null if no
+ * state is stored, the fallback is stale (>5 min), or storage is unavailable.
+ *
+ * @param logger - Optional logger for warning on storage failure
+ */
+declare function retrieveState(logger?: StateLogger): string | null;
+
+declare function cleanupStateStorage(logger?: StateLogger): void;
+
 /**
  * Billing checkout / portal session types.
  *
@@ -716,6 +745,25 @@ interface ContractWizardSubscriptionOptions {
     organizationId?: string;
 }
 
+/** OAuth token operations - exchangeCodeForTokens / refreshAccessToken / signOutToken */
+
+/**
+ * Optional OAuth `state` validation for {@link exchangeCodeForTokens}.
+ *
+ * If a `state` is supplied on EITHER side — `expectedState` (the value persisted
+ * at `redirectToAuthorize`) or `actualState` (the value returned on the callback
+ * URL) — both must be present and equal before any token exchange. A mismatch
+ * OR an omitted counterpart fails closed (no exchange) to defend against CSRF
+ * (RFC 6749 §10.12 / #3841). Validation is skipped only when BOTH are omitted
+ * (backward compatible — callers that don't opt in are unaffected).
+ */
+interface ExchangeCodeForTokensOptions {
+    /** Stored state from `redirectToAuthorize` (e.g. `retrieveState()`) */
+    expectedState?: string;
+    /** State returned on the OAuth callback URL */
+    actualState?: string;
+}
+
 /** Redirect and URL generation - redirectToLogin / redirectToAuthorize / redirectToLogout / getLoginUrl / getSignupUrl / getLogoutUrl */
 
 /**
@@ -755,7 +803,7 @@ declare function createFFIDClient(config: FFIDConfig): {
     getLogoutUrl: (postLogoutRedirectUri?: string) => string;
     getSignupUrl: (redirectUrl?: string) => string;
     createError: (code: string, message: string) => FFIDError;
-    exchangeCodeForTokens: (code: string, codeVerifier?: string) => Promise<FFIDApiResponse<void>>;
+    exchangeCodeForTokens: (code: string, codeVerifier?: string, opts?: ExchangeCodeForTokensOptions) => Promise<FFIDApiResponse<void>>;
     refreshAccessToken: () => Promise<FFIDApiResponse<void>>;
     checkSubscription: (params: {
         userId?: string;
@@ -857,6 +905,52 @@ declare class FFIDSDKError extends Error {
     constructor(code: string, message: string);
 }
 
+/**
+ * OAuth redirect callback handler
+ *
+ * `handleRedirectCallback` is the convenience counterpart to
+ * `redirectToAuthorize`: it reads `code` + `state` from the callback URL,
+ * validates the OAuth `state` against the value persisted at authorize time
+ * (CSRF protection, RFC 6749 §10.12), retrieves the PKCE verifier, exchanges
+ * the code for tokens, and cleans the params out of the URL on success.
+ */
+
+/**
+ * Minimal client surface required by {@link handleRedirectCallback}.
+ * A full {@link FFIDClient} satisfies this structurally.
+ */
+type HandleRedirectCallbackClient = Pick<FFIDClient, 'exchangeCodeForTokens' | 'createError' | 'logger'>;
+/** Options for {@link handleRedirectCallback} */
+interface HandleRedirectCallbackOptions {
+    /**
+     * Callback URL (or query string) to read `code` / `state` from. Accepts an
+     * absolute URL, a relative URL, or a bare query string. Defaults to
+     * `window.location.search` in the browser.
+     */
+    url?: string;
+}
+/**
+ * Complete an OAuth authorization-code redirect.
+ *
+ * Behavior:
+ * 1. Reads `code` + `state` from `options.url ?? window.location.search`.
+ * 2. CSRF guard: if a `state` exists on EITHER side (a stored state from
+ *    authorize OR a `state` on the callback URL), the two MUST match — mismatch,
+ *    a missing stored state, or an **omitted** callback `state` all **fail closed**
+ *    (returns an error, performs no exchange). Validation is skipped ONLY when
+ *    neither side has any state (a genuine no-state flow). Omitting the callback
+ *    `state` does NOT bypass the check (#3841).
+ * 3. Retrieves the PKCE verifier and exchanges the code for tokens.
+ * 4. On success, removes `code` + `state` from the browser URL.
+ *
+ * SSR-safe: when there is no `window` and no `options.url`, no exchange is
+ * attempted and an error result is returned.
+ *
+ * @param client - FFID client (or any object exposing exchangeCodeForTokens / createError / logger)
+ * @param options - Optional callback URL override
+ */
+declare function handleRedirectCallback(client: HandleRedirectCallbackClient, options?: HandleRedirectCallbackOptions): Promise<FFIDApiResponse<void>>;
+
 /**
  * Redirect URI normalization (SDK copy)
  *
@@ -1565,4 +1659,4 @@ declare function createInquiryMethods(deps: InquiryMethodsDeps): {
 };
 type FFIDInquiryClient = ReturnType<typeof createInquiryMethods>;
 
-export { ACCESS_GRANTING_EFFECTIVE_STATUSES, AnnouncementListResponse, BLOCKING_EFFECTIVE_STATUSES, type ComputeEffectiveStatusInput, type ContractWizardFlowType, type ContractWizardResubscribeOptions, type ContractWizardSubscribeOptions, type ContractWizardSubscriptionOptions, DEFAULT_API_BASE_URL, DEFAULT_OAUTH_SCOPES, EffectiveSubscriptionStatus, type FFIDAddMemberParams, type FFIDAddMemberRequest, type FFIDAddMemberResponse, FFIDAnnouncementsApiResponse, type FFIDAnnouncementsClient, FFIDAnnouncementsClientConfig, FFIDAnnouncementsLogger, FFIDApiResponse, type FFIDAssignableMemberRole, type FFIDBillingInterval, FFIDCacheAdapter, type FFIDCancelPendingDowngradeResponse, type FFIDCancelSubscriptionParams, type FFIDCancelSubscriptionResponse, type FFIDChangePlanParams, type FFIDChangePlanResponse, FFIDCheckServiceAccessParams, type FFIDCheckoutSessionResponse, type FFIDClient, FFIDConfig, type FFIDCreateCheckoutParams, type FFIDCreatePortalParams, FFIDError, type FFIDInquiryClient, FFIDInquiryCreateParams, FFIDInquiryCreateResponse, type FFIDListMembersResponse, type FFIDListPlansResponse, FFIDLogger, type FFIDMemberRole, type FFIDMemberStatus, type FFIDNewsletterBodySource, type FFIDNewsletterCampaignStatus, type FFIDNewsletterClient, type FFIDNewsletterConfirmParams, type FFIDNewsletterConfirmResponse, type FFIDNewsletterDispatchParams, type FFIDNewsletterDispatchResponse, type FFIDNewsletterSegment, type FFIDNewsletterSubscribeParams, type FFIDNewsletterSubscribeResponse, type FFIDNewsletterType, type FFIDNewsletterUnsubscribeParams, type FFIDNewsletterUnsubscribeResponse, FFIDOAuthUserInfo, FFIDOAuthUserInfoSubscription, FFIDOrganization, type FFIDOrganizationMember, type FFIDOtpSendResponse, type FFIDOtpVerifyResponse, type FFIDPasswordResetConfirmResponse, type FFIDPasswordResetResponse, type FFIDPasswordResetVerifyResponse, type FFIDPlanChangeLineItem, type FFIDPlanChangePreview, type FFIDPlanChangePreviewResponse, type FFIDPlanInfo, type FFIDPortalSessionResponse, type FFIDPreviewPlanChangeParams, type FFIDPreviewSeatChangeParams, FFIDProfileCallOptions, FFIDProvider, type FFIDProviderProps, FFIDRedirectResult, type FFIDRemoveMemberResponse, type FFIDResetSessionResponse, FFIDSDKError, type FFIDSeatChangeLineItem, type FFIDSeatChangePreview, type FFIDSeatChangePreviewResponse, FFIDServiceAccessDecision, type FFIDServiceInfo, FFIDSessionResponse, type FFIDSubscribeParams, type FFIDSubscribeResponse, FFIDSubscription, FFIDSubscriptionCheckResponse, FFIDSubscriptionContextValue, type FFIDSubscriptionDetail, FFIDSubscriptionStatus, type FFIDSubscriptionSummary, type FFIDSupportedCurrency, type FFIDUpdateMemberRoleResponse, FFIDUpdateUserProfileRequest, FFIDUser, FFIDUserProfile, FFIDVerifyAccessTokenOptions, FFID_ANNOUNCEMENTS_ERROR_CODES, FFID_NEWSLETTER_DISPATCH_MAX_RECIPIENTS, FFID_NEWSLETTER_TYPES, type KVNamespaceLike, ListAnnouncementsOptions, type NormalizeRedirectUriResult, type RedirectToAuthorizeOptions, type TokenData, type TokenStore, type UseFFIDReturn, type UseRequireActiveSubscriptionOptions, type UseRequireActiveSubscriptionReturn, type WithFFIDAuthOptions, type WithSubscriptionOptions, computeEffectiveStatusFromSession, createFFIDAnnouncementsClient, createFFIDClient, createKVCacheAdapter, createMemoryCacheAdapter, createTokenStore, generateCodeChallenge, generateCodeVerifier, hasAccessFromUserinfo, isBlockedFromUserinfo, normalizeRedirectUri, retrieveCodeVerifier, storeCodeVerifier, useFFID, useRequireActiveSubscription, useSubscription, withFFIDAuth, withSubscription };
+export { ACCESS_GRANTING_EFFECTIVE_STATUSES, AnnouncementListResponse, BLOCKING_EFFECTIVE_STATUSES, type ComputeEffectiveStatusInput, type ContractWizardFlowType, type ContractWizardResubscribeOptions, type ContractWizardSubscribeOptions, type ContractWizardSubscriptionOptions, DEFAULT_API_BASE_URL, DEFAULT_OAUTH_SCOPES, EffectiveSubscriptionStatus, type ExchangeCodeForTokensOptions, type FFIDAddMemberParams, type FFIDAddMemberRequest, type FFIDAddMemberResponse, FFIDAnnouncementsApiResponse, type FFIDAnnouncementsClient, FFIDAnnouncementsClientConfig, FFIDAnnouncementsLogger, FFIDApiResponse, type FFIDAssignableMemberRole, type FFIDBillingInterval, FFIDCacheAdapter, type FFIDCancelPendingDowngradeResponse, type FFIDCancelSubscriptionParams, type FFIDCancelSubscriptionResponse, type FFIDChangePlanParams, type FFIDChangePlanResponse, FFIDCheckServiceAccessParams, type FFIDCheckoutSessionResponse, type FFIDClient, FFIDConfig, type FFIDCreateCheckoutParams, type FFIDCreatePortalParams, FFIDError, type FFIDInquiryClient, FFIDInquiryCreateParams, FFIDInquiryCreateResponse, type FFIDListMembersResponse, type FFIDListPlansResponse, FFIDLogger, type FFIDMemberRole, type FFIDMemberStatus, type FFIDNewsletterBodySource, type FFIDNewsletterCampaignStatus, type FFIDNewsletterClient, type FFIDNewsletterConfirmParams, type FFIDNewsletterConfirmResponse, type FFIDNewsletterDispatchParams, type FFIDNewsletterDispatchResponse, type FFIDNewsletterSegment, type FFIDNewsletterSubscribeParams, type FFIDNewsletterSubscribeResponse, type FFIDNewsletterType, type FFIDNewsletterUnsubscribeParams, type FFIDNewsletterUnsubscribeResponse, FFIDOAuthUserInfo, FFIDOAuthUserInfoSubscription, FFIDOrganization, type FFIDOrganizationMember, type FFIDOtpSendResponse, type FFIDOtpVerifyResponse, type FFIDPasswordResetConfirmResponse, type FFIDPasswordResetResponse, type FFIDPasswordResetVerifyResponse, type FFIDPlanChangeLineItem, type FFIDPlanChangePreview, type FFIDPlanChangePreviewResponse, type FFIDPlanInfo, type FFIDPortalSessionResponse, type FFIDPreviewPlanChangeParams, type FFIDPreviewSeatChangeParams, FFIDProfileCallOptions, FFIDProvider, type FFIDProviderProps, FFIDRedirectResult, type FFIDRemoveMemberResponse, type FFIDResetSessionResponse, FFIDSDKError, type FFIDSeatChangeLineItem, type FFIDSeatChangePreview, type FFIDSeatChangePreviewResponse, FFIDServiceAccessDecision, type FFIDServiceInfo, FFIDSessionResponse, type FFIDSubscribeParams, type FFIDSubscribeResponse, FFIDSubscription, FFIDSubscriptionCheckResponse, FFIDSubscriptionContextValue, type FFIDSubscriptionDetail, FFIDSubscriptionStatus, type FFIDSubscriptionSummary, type FFIDSupportedCurrency, type FFIDUpdateMemberRoleResponse, FFIDUpdateUserProfileRequest, FFIDUser, FFIDUserProfile, FFIDVerifyAccessTokenOptions, FFID_ANNOUNCEMENTS_ERROR_CODES, FFID_NEWSLETTER_DISPATCH_MAX_RECIPIENTS, FFID_NEWSLETTER_TYPES, type HandleRedirectCallbackClient, type HandleRedirectCallbackOptions, type KVNamespaceLike, ListAnnouncementsOptions, type NormalizeRedirectUriResult, type RedirectToAuthorizeOptions, type TokenData, type TokenStore, type UseFFIDReturn, type UseRequireActiveSubscriptionOptions, type UseRequireActiveSubscriptionReturn, type WithFFIDAuthOptions, type WithSubscriptionOptions, cleanupStateStorage as clearState, computeEffectiveStatusFromSession, createFFIDAnnouncementsClient, createFFIDClient, createKVCacheAdapter, createMemoryCacheAdapter, createTokenStore, generateCodeChallenge, generateCodeVerifier, handleRedirectCallback, hasAccessFromUserinfo, isBlockedFromUserinfo, normalizeRedirectUri, retrieveCodeVerifier, retrieveState, storeCodeVerifier, storeState, useFFID, useRequireActiveSubscription, useSubscription, withFFIDAuth, withSubscription };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { F as FFIDSubscriptionStatus, a as FFIDConfig, b as FFIDApiResponse, c as FFIDSessionResponse, d as FFIDRedirectResult, e as FFIDError, f as FFIDSubscriptionCheckResponse, g as FFIDCheckServiceAccessParams, h as FFIDServiceAccessDecision, i as FFIDProfileCallOptions, j as FFIDUserProfile, k as FFIDUpdateUserProfileRequest, l as FFIDAnalyticsConfig, m as FFIDVerifyAccessTokenOptions, n as FFIDOAuthUserInfo, o as FFIDInquiryCreateParams, p as FFIDInquiryCreateResponse, q as FFIDAuthMode, r as FFIDLogger, s as FFIDCacheAdapter, t as FFIDUser, u as FFIDOrganization, v as FFIDSubscription, w as FFIDSubscriptionContextValue, E as EffectiveSubscriptionStatus, x as FFIDOAuthUserInfoSubscription, y as FFIDAnnouncementsClientConfig, L as ListAnnouncementsOptions, z as FFIDAnnouncementsApiResponse, A as AnnouncementListResponse, B as FFIDAnnouncementsLogger } from './index-DqsWKU16.js';
-export { C as Announcement, D as AnnouncementStatus, G as AnnouncementType, H as EFFECTIVE_SUBSCRIPTION_STATUSES, I as FFIDAnnouncementBadge, J as FFIDAnnouncementList, K as FFIDAnnouncementsError, M as FFIDAnnouncementsErrorCode, N as FFIDAnnouncementsServerResponse, O as FFIDCacheConfig, P as FFIDContextValue, Q as FFIDInquiryCategory, R as FFIDInquiryCategorySite2026, S as FFIDInquiryForm, T as FFIDInquiryFormCategoryItem, U as FFIDInquiryFormClassNames, V as FFIDInquiryFormLegalLayout, W as FFIDInquiryFormOrganization, X as FFIDInquiryFormPlaceholderContext, Y as FFIDInquiryFormPrefill, Z as FFIDInquiryFormProps, _ as FFIDInquiryFormSubmitData, $ as FFIDInquiryFormSubmitResult, a0 as FFIDJwtClaims, a1 as FFIDLoginButton, a2 as FFIDOAuthTokenResponse, a3 as FFIDOAuthUserInfoMemberRole, a4 as FFIDOrganizationSwitcher, a5 as FFIDRedirectErrorCode, a6 as FFIDSeatModel, a7 as FFIDServiceAccessDenialReason, a8 as FFIDServiceAccessFailPolicy, a9 as FFIDSubscriptionBadge, aa as FFIDTokenIntrospectionResponse, ab as FFIDUserMenu, ac as FFID_INQUIRY_CATEGORIES, ad as FFID_INQUIRY_CATEGORIES_SITE_2026, ae as UseFFIDAnnouncementsOptions, af as UseFFIDAnnouncementsReturn, ag as isFFIDInquiryCategorySite2026, ah as useFFIDAnnouncements } from './index-DqsWKU16.js';
+import { F as FFIDSubscriptionStatus, a as FFIDConfig, b as FFIDApiResponse, c as FFIDSessionResponse, d as FFIDRedirectResult, e as FFIDError, f as FFIDSubscriptionCheckResponse, g as FFIDCheckServiceAccessParams, h as FFIDServiceAccessDecision, i as FFIDProfileCallOptions, j as FFIDUserProfile, k as FFIDUpdateUserProfileRequest, l as FFIDAnalyticsConfig, m as FFIDVerifyAccessTokenOptions, n as FFIDOAuthUserInfo, o as FFIDInquiryCreateParams, p as FFIDInquiryCreateResponse, q as FFIDAuthMode, r as FFIDLogger, s as FFIDCacheAdapter, t as FFIDUser, u as FFIDOrganization, v as FFIDSubscription, w as FFIDSubscriptionContextValue, E as EffectiveSubscriptionStatus, x as FFIDOAuthUserInfoSubscription, y as FFIDAnnouncementsClientConfig, L as ListAnnouncementsOptions, z as FFIDAnnouncementsApiResponse, A as AnnouncementListResponse, B as FFIDAnnouncementsLogger } from './index-C6dnexXf.js';
+export { C as Announcement, D as AnnouncementStatus, G as AnnouncementType, H as EFFECTIVE_SUBSCRIPTION_STATUSES, I as FFIDAnnouncementBadge, J as FFIDAnnouncementList, K as FFIDAnnouncementsError, M as FFIDAnnouncementsErrorCode, N as FFIDAnnouncementsServerResponse, O as FFIDCacheConfig, P as FFIDContextValue, Q as FFIDInquiryCategory, R as FFIDInquiryCategorySite2026, S as FFIDInquiryForm, T as FFIDInquiryFormCategoryItem, U as FFIDInquiryFormClassNames, V as FFIDInquiryFormLegalLayout, W as FFIDInquiryFormOrganization, X as FFIDInquiryFormPlaceholderContext, Y as FFIDInquiryFormPrefill, Z as FFIDInquiryFormProps, _ as FFIDInquiryFormSubmitData, $ as FFIDInquiryFormSubmitResult, a0 as FFIDJwtClaims, a1 as FFIDLoginButton, a2 as FFIDOAuthTokenResponse, a3 as FFIDOAuthUserInfoMemberRole, a4 as FFIDOrganizationSwitcher, a5 as FFIDRedirectErrorCode, a6 as FFIDSeatModel, a7 as FFIDServiceAccessDenialReason, a8 as FFIDServiceAccessFailPolicy, a9 as FFIDSubscriptionBadge, aa as FFIDTokenIntrospectionResponse, ab as FFIDUserMenu, ac as FFID_INQUIRY_CATEGORIES, ad as FFID_INQUIRY_CATEGORIES_SITE_2026, ae as UseFFIDAnnouncementsOptions, af as UseFFIDAnnouncementsReturn, ag as isFFIDInquiryCategorySite2026, ah as useFFIDAnnouncements } from './index-C6dnexXf.js';
 export { A as ALL_DENIED_EXCEPT_NECESSARY, i as CONSENT_COOKIE_NAME, j as CONSENT_DISMISSAL_TIMESTAMP_KEY, l as COOKIE_VERSION, D as DEFAULT_CONSENT_ERROR_MESSAGES, o as FFIDAnalyticsProvider, p as FFIDAnalyticsProviderProps, c as FFIDConsentCategories, r as FFIDConsentCategoryCode, e as FFIDConsentCategoryMetadata, w as FFIDConsentError, x as FFIDConsentErrorCode, y as FFIDConsentMergeStrategy, B as FFIDConsentMergeWarning, E as FFIDConsentMergeWarningEvent, F as FFIDConsentResult, I as FFIDConsentSource, a as FFIDConsentState, d as FFIDConsentSyncResult, M as FFIDCookieBanner, N as FFIDCookieBannerClassNames, O as FFIDCookieBannerProps, Q as FFIDCookieLink, R as FFIDCookieLinkProps, f as FFIDCookiePolicy, T as FFIDCookieSettings, U as FFIDCookieSettingsClassNames, V as FFIDCookieSettingsProps, _ as FFID_CONSENT_ERROR_CODES, ae as UseFFIDConsentPreferencesReturn, af as UseFFIDConsentReturn, ag as clearConsentDismissalTimestamp, aj as decodeConsentCookie, al as encodeConsentCookie, an as readConsentCookie, ao as readConsentDismissalTimestamp, aq as useFFIDConsent, ar as useFFIDConsentPreferences, as as writeConsentCookie, at as writeConsentDismissalTimestamp } from './FFIDCookieLink-D1WwE_ZO.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode, ComponentType, FC } from 'react';
@@ -122,6 +122,35 @@ declare function storeCodeVerifier(verifier: string, logger?: PKCELogger): boole
  */
 declare function retrieveCodeVerifier(logger?: PKCELogger): string | null;
 
+/** Logger interface matching FFIDLogger for optional warning output */
+interface StateLogger {
+    warn: (...args: unknown[]) => void;
+}
+/**
+ * Store the OAuth `state` for later retrieval.
+ *
+ * Writes to both sessionStorage (primary) and localStorage (fallback for iOS
+ * WebKit sessionStorage eviction during external OAuth bounces). Returns true
+ * if at least one write succeeded.
+ *
+ * @param state - The OAuth state value to store
+ * @param logger - Optional logger for warning on storage failure
+ * @returns true if stored in at least one storage, false otherwise
+ */
+declare function storeState(state: string, logger?: StateLogger): boolean;
+/**
+ * Retrieve and remove the OAuth `state`.
+ *
+ * Reads from sessionStorage first, falls back to localStorage (with 5-minute TTL).
+ * Removes from all storages after retrieval (one-time use). Returns null if no
+ * state is stored, the fallback is stale (>5 min), or storage is unavailable.
+ *
+ * @param logger - Optional logger for warning on storage failure
+ */
+declare function retrieveState(logger?: StateLogger): string | null;
+
+declare function cleanupStateStorage(logger?: StateLogger): void;
+
 /**
  * Billing checkout / portal session types.
  *
@@ -716,6 +745,25 @@ interface ContractWizardSubscriptionOptions {
     organizationId?: string;
 }
 
+/** OAuth token operations - exchangeCodeForTokens / refreshAccessToken / signOutToken */
+
+/**
+ * Optional OAuth `state` validation for {@link exchangeCodeForTokens}.
+ *
+ * If a `state` is supplied on EITHER side — `expectedState` (the value persisted
+ * at `redirectToAuthorize`) or `actualState` (the value returned on the callback
+ * URL) — both must be present and equal before any token exchange. A mismatch
+ * OR an omitted counterpart fails closed (no exchange) to defend against CSRF
+ * (RFC 6749 §10.12 / #3841). Validation is skipped only when BOTH are omitted
+ * (backward compatible — callers that don't opt in are unaffected).
+ */
+interface ExchangeCodeForTokensOptions {
+    /** Stored state from `redirectToAuthorize` (e.g. `retrieveState()`) */
+    expectedState?: string;
+    /** State returned on the OAuth callback URL */
+    actualState?: string;
+}
+
 /** Redirect and URL generation - redirectToLogin / redirectToAuthorize / redirectToLogout / getLoginUrl / getSignupUrl / getLogoutUrl */
 
 /**
@@ -755,7 +803,7 @@ declare function createFFIDClient(config: FFIDConfig): {
     getLogoutUrl: (postLogoutRedirectUri?: string) => string;
     getSignupUrl: (redirectUrl?: string) => string;
     createError: (code: string, message: string) => FFIDError;
-    exchangeCodeForTokens: (code: string, codeVerifier?: string) => Promise<FFIDApiResponse<void>>;
+    exchangeCodeForTokens: (code: string, codeVerifier?: string, opts?: ExchangeCodeForTokensOptions) => Promise<FFIDApiResponse<void>>;
     refreshAccessToken: () => Promise<FFIDApiResponse<void>>;
     checkSubscription: (params: {
         userId?: string;
@@ -857,6 +905,52 @@ declare class FFIDSDKError extends Error {
     constructor(code: string, message: string);
 }
 
+/**
+ * OAuth redirect callback handler
+ *
+ * `handleRedirectCallback` is the convenience counterpart to
+ * `redirectToAuthorize`: it reads `code` + `state` from the callback URL,
+ * validates the OAuth `state` against the value persisted at authorize time
+ * (CSRF protection, RFC 6749 §10.12), retrieves the PKCE verifier, exchanges
+ * the code for tokens, and cleans the params out of the URL on success.
+ */
+
+/**
+ * Minimal client surface required by {@link handleRedirectCallback}.
+ * A full {@link FFIDClient} satisfies this structurally.
+ */
+type HandleRedirectCallbackClient = Pick<FFIDClient, 'exchangeCodeForTokens' | 'createError' | 'logger'>;
+/** Options for {@link handleRedirectCallback} */
+interface HandleRedirectCallbackOptions {
+    /**
+     * Callback URL (or query string) to read `code` / `state` from. Accepts an
+     * absolute URL, a relative URL, or a bare query string. Defaults to
+     * `window.location.search` in the browser.
+     */
+    url?: string;
+}
+/**
+ * Complete an OAuth authorization-code redirect.
+ *
+ * Behavior:
+ * 1. Reads `code` + `state` from `options.url ?? window.location.search`.
+ * 2. CSRF guard: if a `state` exists on EITHER side (a stored state from
+ *    authorize OR a `state` on the callback URL), the two MUST match — mismatch,
+ *    a missing stored state, or an **omitted** callback `state` all **fail closed**
+ *    (returns an error, performs no exchange). Validation is skipped ONLY when
+ *    neither side has any state (a genuine no-state flow). Omitting the callback
+ *    `state` does NOT bypass the check (#3841).
+ * 3. Retrieves the PKCE verifier and exchanges the code for tokens.
+ * 4. On success, removes `code` + `state` from the browser URL.
+ *
+ * SSR-safe: when there is no `window` and no `options.url`, no exchange is
+ * attempted and an error result is returned.
+ *
+ * @param client - FFID client (or any object exposing exchangeCodeForTokens / createError / logger)
+ * @param options - Optional callback URL override
+ */
+declare function handleRedirectCallback(client: HandleRedirectCallbackClient, options?: HandleRedirectCallbackOptions): Promise<FFIDApiResponse<void>>;
+
 /**
  * Redirect URI normalization (SDK copy)
  *
@@ -1565,4 +1659,4 @@ declare function createInquiryMethods(deps: InquiryMethodsDeps): {
 };
 type FFIDInquiryClient = ReturnType<typeof createInquiryMethods>;
 
-export { ACCESS_GRANTING_EFFECTIVE_STATUSES, AnnouncementListResponse, BLOCKING_EFFECTIVE_STATUSES, type ComputeEffectiveStatusInput, type ContractWizardFlowType, type ContractWizardResubscribeOptions, type ContractWizardSubscribeOptions, type ContractWizardSubscriptionOptions, DEFAULT_API_BASE_URL, DEFAULT_OAUTH_SCOPES, EffectiveSubscriptionStatus, type FFIDAddMemberParams, type FFIDAddMemberRequest, type FFIDAddMemberResponse, FFIDAnnouncementsApiResponse, type FFIDAnnouncementsClient, FFIDAnnouncementsClientConfig, FFIDAnnouncementsLogger, FFIDApiResponse, type FFIDAssignableMemberRole, type FFIDBillingInterval, FFIDCacheAdapter, type FFIDCancelPendingDowngradeResponse, type FFIDCancelSubscriptionParams, type FFIDCancelSubscriptionResponse, type FFIDChangePlanParams, type FFIDChangePlanResponse, FFIDCheckServiceAccessParams, type FFIDCheckoutSessionResponse, type FFIDClient, FFIDConfig, type FFIDCreateCheckoutParams, type FFIDCreatePortalParams, FFIDError, type FFIDInquiryClient, FFIDInquiryCreateParams, FFIDInquiryCreateResponse, type FFIDListMembersResponse, type FFIDListPlansResponse, FFIDLogger, type FFIDMemberRole, type FFIDMemberStatus, type FFIDNewsletterBodySource, type FFIDNewsletterCampaignStatus, type FFIDNewsletterClient, type FFIDNewsletterConfirmParams, type FFIDNewsletterConfirmResponse, type FFIDNewsletterDispatchParams, type FFIDNewsletterDispatchResponse, type FFIDNewsletterSegment, type FFIDNewsletterSubscribeParams, type FFIDNewsletterSubscribeResponse, type FFIDNewsletterType, type FFIDNewsletterUnsubscribeParams, type FFIDNewsletterUnsubscribeResponse, FFIDOAuthUserInfo, FFIDOAuthUserInfoSubscription, FFIDOrganization, type FFIDOrganizationMember, type FFIDOtpSendResponse, type FFIDOtpVerifyResponse, type FFIDPasswordResetConfirmResponse, type FFIDPasswordResetResponse, type FFIDPasswordResetVerifyResponse, type FFIDPlanChangeLineItem, type FFIDPlanChangePreview, type FFIDPlanChangePreviewResponse, type FFIDPlanInfo, type FFIDPortalSessionResponse, type FFIDPreviewPlanChangeParams, type FFIDPreviewSeatChangeParams, FFIDProfileCallOptions, FFIDProvider, type FFIDProviderProps, FFIDRedirectResult, type FFIDRemoveMemberResponse, type FFIDResetSessionResponse, FFIDSDKError, type FFIDSeatChangeLineItem, type FFIDSeatChangePreview, type FFIDSeatChangePreviewResponse, FFIDServiceAccessDecision, type FFIDServiceInfo, FFIDSessionResponse, type FFIDSubscribeParams, type FFIDSubscribeResponse, FFIDSubscription, FFIDSubscriptionCheckResponse, FFIDSubscriptionContextValue, type FFIDSubscriptionDetail, FFIDSubscriptionStatus, type FFIDSubscriptionSummary, type FFIDSupportedCurrency, type FFIDUpdateMemberRoleResponse, FFIDUpdateUserProfileRequest, FFIDUser, FFIDUserProfile, FFIDVerifyAccessTokenOptions, FFID_ANNOUNCEMENTS_ERROR_CODES, FFID_NEWSLETTER_DISPATCH_MAX_RECIPIENTS, FFID_NEWSLETTER_TYPES, type KVNamespaceLike, ListAnnouncementsOptions, type NormalizeRedirectUriResult, type RedirectToAuthorizeOptions, type TokenData, type TokenStore, type UseFFIDReturn, type UseRequireActiveSubscriptionOptions, type UseRequireActiveSubscriptionReturn, type WithFFIDAuthOptions, type WithSubscriptionOptions, computeEffectiveStatusFromSession, createFFIDAnnouncementsClient, createFFIDClient, createKVCacheAdapter, createMemoryCacheAdapter, createTokenStore, generateCodeChallenge, generateCodeVerifier, hasAccessFromUserinfo, isBlockedFromUserinfo, normalizeRedirectUri, retrieveCodeVerifier, storeCodeVerifier, useFFID, useRequireActiveSubscription, useSubscription, withFFIDAuth, withSubscription };
+export { ACCESS_GRANTING_EFFECTIVE_STATUSES, AnnouncementListResponse, BLOCKING_EFFECTIVE_STATUSES, type ComputeEffectiveStatusInput, type ContractWizardFlowType, type ContractWizardResubscribeOptions, type ContractWizardSubscribeOptions, type ContractWizardSubscriptionOptions, DEFAULT_API_BASE_URL, DEFAULT_OAUTH_SCOPES, EffectiveSubscriptionStatus, type ExchangeCodeForTokensOptions, type FFIDAddMemberParams, type FFIDAddMemberRequest, type FFIDAddMemberResponse, FFIDAnnouncementsApiResponse, type FFIDAnnouncementsClient, FFIDAnnouncementsClientConfig, FFIDAnnouncementsLogger, FFIDApiResponse, type FFIDAssignableMemberRole, type FFIDBillingInterval, FFIDCacheAdapter, type FFIDCancelPendingDowngradeResponse, type FFIDCancelSubscriptionParams, type FFIDCancelSubscriptionResponse, type FFIDChangePlanParams, type FFIDChangePlanResponse, FFIDCheckServiceAccessParams, type FFIDCheckoutSessionResponse, type FFIDClient, FFIDConfig, type FFIDCreateCheckoutParams, type FFIDCreatePortalParams, FFIDError, type FFIDInquiryClient, FFIDInquiryCreateParams, FFIDInquiryCreateResponse, type FFIDListMembersResponse, type FFIDListPlansResponse, FFIDLogger, type FFIDMemberRole, type FFIDMemberStatus, type FFIDNewsletterBodySource, type FFIDNewsletterCampaignStatus, type FFIDNewsletterClient, type FFIDNewsletterConfirmParams, type FFIDNewsletterConfirmResponse, type FFIDNewsletterDispatchParams, type FFIDNewsletterDispatchResponse, type FFIDNewsletterSegment, type FFIDNewsletterSubscribeParams, type FFIDNewsletterSubscribeResponse, type FFIDNewsletterType, type FFIDNewsletterUnsubscribeParams, type FFIDNewsletterUnsubscribeResponse, FFIDOAuthUserInfo, FFIDOAuthUserInfoSubscription, FFIDOrganization, type FFIDOrganizationMember, type FFIDOtpSendResponse, type FFIDOtpVerifyResponse, type FFIDPasswordResetConfirmResponse, type FFIDPasswordResetResponse, type FFIDPasswordResetVerifyResponse, type FFIDPlanChangeLineItem, type FFIDPlanChangePreview, type FFIDPlanChangePreviewResponse, type FFIDPlanInfo, type FFIDPortalSessionResponse, type FFIDPreviewPlanChangeParams, type FFIDPreviewSeatChangeParams, FFIDProfileCallOptions, FFIDProvider, type FFIDProviderProps, FFIDRedirectResult, type FFIDRemoveMemberResponse, type FFIDResetSessionResponse, FFIDSDKError, type FFIDSeatChangeLineItem, type FFIDSeatChangePreview, type FFIDSeatChangePreviewResponse, FFIDServiceAccessDecision, type FFIDServiceInfo, FFIDSessionResponse, type FFIDSubscribeParams, type FFIDSubscribeResponse, FFIDSubscription, FFIDSubscriptionCheckResponse, FFIDSubscriptionContextValue, type FFIDSubscriptionDetail, FFIDSubscriptionStatus, type FFIDSubscriptionSummary, type FFIDSupportedCurrency, type FFIDUpdateMemberRoleResponse, FFIDUpdateUserProfileRequest, FFIDUser, FFIDUserProfile, FFIDVerifyAccessTokenOptions, FFID_ANNOUNCEMENTS_ERROR_CODES, FFID_NEWSLETTER_DISPATCH_MAX_RECIPIENTS, FFID_NEWSLETTER_TYPES, type HandleRedirectCallbackClient, type HandleRedirectCallbackOptions, type KVNamespaceLike, ListAnnouncementsOptions, type NormalizeRedirectUriResult, type RedirectToAuthorizeOptions, type TokenData, type TokenStore, type UseFFIDReturn, type UseRequireActiveSubscriptionOptions, type UseRequireActiveSubscriptionReturn, type WithFFIDAuthOptions, type WithSubscriptionOptions, cleanupStateStorage as clearState, computeEffectiveStatusFromSession, createFFIDAnnouncementsClient, createFFIDClient, createKVCacheAdapter, createMemoryCacheAdapter, createTokenStore, generateCodeChallenge, generateCodeVerifier, handleRedirectCallback, hasAccessFromUserinfo, isBlockedFromUserinfo, normalizeRedirectUri, retrieveCodeVerifier, retrieveState, storeCodeVerifier, storeState, useFFID, useRequireActiveSubscription, useSubscription, withFFIDAuth, withSubscription };

package/dist/index.js

@@ -1,5 +1,5 @@
-import { useFFIDContext, useSubscription } from './chunk-KB2JG64Z.js';
-export { ACCESS_GRANTING_EFFECTIVE_STATUSES, BLOCKING_EFFECTIVE_STATUSES, DEFAULT_API_BASE_URL, DEFAULT_OAUTH_SCOPES, EFFECTIVE_SUBSCRIPTION_STATUSES, FFIDAnnouncementBadge, FFIDAnnouncementList, FFIDInquiryForm, FFIDLoginButton, FFIDOrganizationSwitcher, FFIDProvider, FFIDSDKError, FFIDSubscriptionBadge, FFIDUserMenu, FFID_ANNOUNCEMENTS_ERROR_CODES, FFID_INQUIRY_CATEGORIES, FFID_INQUIRY_CATEGORIES_SITE_2026, computeEffectiveStatusFromSession, createFFIDAnnouncementsClient, createFFIDClient, createTokenStore, generateCodeChallenge, generateCodeVerifier, hasAccessFromUserinfo, isBlockedFromUserinfo, isFFIDInquiryCategorySite2026, normalizeRedirectUri, retrieveCodeVerifier, storeCodeVerifier, useFFID, useFFIDAnnouncements, useSubscription, withSubscription } from './chunk-KB2JG64Z.js';
+import { useFFIDContext, useSubscription } from './chunk-RATTQIKM.js';
+export { ACCESS_GRANTING_EFFECTIVE_STATUSES, BLOCKING_EFFECTIVE_STATUSES, DEFAULT_API_BASE_URL, DEFAULT_OAUTH_SCOPES, EFFECTIVE_SUBSCRIPTION_STATUSES, FFIDAnnouncementBadge, FFIDAnnouncementList, FFIDInquiryForm, FFIDLoginButton, FFIDOrganizationSwitcher, FFIDProvider, FFIDSDKError, FFIDSubscriptionBadge, FFIDUserMenu, FFID_ANNOUNCEMENTS_ERROR_CODES, FFID_INQUIRY_CATEGORIES, FFID_INQUIRY_CATEGORIES_SITE_2026, cleanupStateStorage as clearState, computeEffectiveStatusFromSession, createFFIDAnnouncementsClient, createFFIDClient, createTokenStore, generateCodeChallenge, generateCodeVerifier, handleRedirectCallback, hasAccessFromUserinfo, isBlockedFromUserinfo, isFFIDInquiryCategorySite2026, normalizeRedirectUri, retrieveCodeVerifier, retrieveState, storeCodeVerifier, storeState, useFFID, useFFIDAnnouncements, useSubscription, withSubscription } from './chunk-RATTQIKM.js';
 export { ALL_DENIED_EXCEPT_NECESSARY, CONSENT_COOKIE_NAME, CONSENT_DISMISSAL_TIMESTAMP_KEY, COOKIE_VERSION, DEFAULT_CONSENT_ERROR_MESSAGES, FFIDAnalyticsProvider, FFIDConsentError, FFIDCookieBanner, FFIDCookieLink, FFIDCookieSettings, FFID_CONSENT_ERROR_CODES, clearConsentDismissalTimestamp, decodeConsentCookie, encodeConsentCookie, readConsentCookie, readConsentDismissalTimestamp, useFFIDConsent, useFFIDConsentPreferences, writeConsentCookie, writeConsentDismissalTimestamp } from './chunk-M4N2PUX6.js';
 import { useEffect, useRef } from 'react';
 import { jsx, Fragment } from 'react/jsx-runtime';

package/dist/server/index.cjs

@@ -119,6 +119,9 @@ function normalizeUserinfo(raw) {
   return {
     sub: raw.sub,
     email: raw.email,
+    // #3791: undefined → undefined を保つ（false に丸めない）。古い FFID は wire に
+    // 含めないため、consumer は undefined を「未確認」ではなく「不明」として扱える。
+    emailVerified: raw.email_verified,
     name: raw.name,
     picture: raw.picture,
     companyName: raw.company_name ?? null,
@@ -374,6 +377,9 @@ function createVerifyAccessToken(deps) {
     const base = {
       sub: introspectResponse.sub,
       email: introspectResponse.email ?? null,
+      // #3791: preserve undefined (do NOT coerce to false) so introspect-strategy
+      // callers can distinguish "verified" / "not verified" / "older server".
+      email_verified: introspectResponse.email_verified,
       name: introspectResponse.name ?? null,
       picture: introspectResponse.picture ?? null,
       company_name: introspectResponse.company_name ?? null,
@@ -929,7 +935,7 @@ function createProfileMethods(deps) {
 }
 
 // src/client/version-check.ts
-var SDK_VERSION = "5.12.0";
+var SDK_VERSION = "5.13.0";
 var SDK_USER_AGENT = `FFID-SDK/${SDK_VERSION} (TypeScript)`;
 var SDK_VERSION_HEADER = "X-FFID-SDK-Version";
 function sdkHeaders() {
@@ -1001,9 +1007,20 @@ function createOAuthTokenMethods(deps) {
     logger,
     errorCodes
   } = deps;
-  async function exchangeCodeForTokens(code, codeVerifier) {
+  async function exchangeCodeForTokens(code, codeVerifier, opts) {
     const url = `${baseUrl}${OAUTH_TOKEN_ENDPOINT}`;
     logger.debug("Exchanging code for tokens:", url);
+    if (opts?.expectedState !== void 0 || opts?.actualState !== void 0) {
+      if (opts?.expectedState !== opts?.actualState) {
+        logger.error("Token exchange aborted: OAuth state mismatch or omitted (possible CSRF)");
+        return {
+          error: {
+            code: errorCodes.STATE_MISMATCH_ERROR,
+            message: "OAuth state \u304C\u4E00\u81F4\u3057\u307E\u305B\u3093\u3002CSRF \u306E\u53EF\u80FD\u6027\u304C\u3042\u308B\u305F\u3081\u8A8D\u8A3C\u3092\u4E2D\u6B62\u3057\u307E\u3057\u305F"
+          }
+        };
+      }
+    }
     const effectiveRedirectUri = resolvedRedirectUri ?? (typeof window !== "undefined" ? window.location.origin + window.location.pathname : null);
     if (!effectiveRedirectUri) {
       logger.error("redirectUri is required for token exchange in SSR environments. Set config.redirectUri explicitly.");
@@ -1448,6 +1465,46 @@ function base64UrlEncode(buffer) {
   return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
 
+// src/auth/state.ts
+var STATE_STORAGE_KEY = "ffid_oauth_state";
+var STATE_FALLBACK_STORAGE_KEY = "ffid_oauth_state_fb";
+var STATE_FALLBACK_TIMESTAMP_KEY = "ffid_oauth_state_fb_ts";
+function storeState(state, logger) {
+  if (typeof window === "undefined") {
+    logger?.warn("storeState: storage is not available in SSR context");
+    return false;
+  }
+  let sessionStored = false;
+  try {
+    window.sessionStorage.setItem(STATE_STORAGE_KEY, state);
+    sessionStored = true;
+  } catch (error) {
+    logger?.warn("storeState: sessionStorage \u3078\u306E\u4FDD\u5B58\u306B\u5931\u6557\u3057\u307E\u3057\u305F:", error);
+  }
+  let localStored = false;
+  try {
+    window.localStorage.setItem(STATE_FALLBACK_STORAGE_KEY, state);
+    window.localStorage.setItem(STATE_FALLBACK_TIMESTAMP_KEY, String(Date.now()));
+    localStored = true;
+  } catch (error) {
+    logger?.warn("storeState: localStorage fallback \u3078\u306E\u4FDD\u5B58\u306B\u5931\u6557\u3057\u307E\u3057\u305F:", error);
+  }
+  return sessionStored || localStored;
+}
+function cleanupStateStorage(logger) {
+  try {
+    window.sessionStorage.removeItem(STATE_STORAGE_KEY);
+  } catch (error) {
+    logger?.warn("retrieveState: sessionStorage \u306E\u30AF\u30EA\u30FC\u30F3\u30A2\u30C3\u30D7\u306B\u5931\u6557\u3057\u307E\u3057\u305F:", error);
+  }
+  try {
+    window.localStorage.removeItem(STATE_FALLBACK_STORAGE_KEY);
+    window.localStorage.removeItem(STATE_FALLBACK_TIMESTAMP_KEY);
+  } catch (error) {
+    logger?.warn("retrieveState: localStorage \u306E\u30AF\u30EA\u30FC\u30F3\u30A2\u30C3\u30D7\u306B\u5931\u6557\u3057\u307E\u3057\u305F:", error);
+  }
+}
+
 // src/client/redirect.ts
 var OAUTH_AUTHORIZE_ENDPOINT = "/api/v1/oauth/authorize";
 var AUTH_LOGOUT_ENDPOINT = "/api/v1/auth/logout";
@@ -1579,6 +1636,7 @@ function createRedirectMethods(deps) {
     const recentCount = getRecentRedirectCount(authorizeKey, now, logger);
     if (recentCount >= REDIRECT_LOOP_THRESHOLD) {
       cleanupVerifierStorage(logger);
+      cleanupStateStorage(logger);
       logger.warn("[FFID SDK] redirect loop detected \u2014 \u81EA\u52D5\u30EA\u30C0\u30A4\u30EC\u30AF\u30C8\u3092\u505C\u6B62\u3057\u307E\u3057\u305F", {
         authorizeKey,
         recentCount,
@@ -1602,6 +1660,11 @@ function createRedirectMethods(deps) {
       return { success: false, error: errorMessage };
     }
     const state = generateRandomState();
+    if (!storeState(state, logger)) {
+      logger.error(
+        "redirectToAuthorize: OAuth state \u3092\u4FDD\u5B58\u3067\u304D\u307E\u305B\u3093\u3067\u3057\u305F\uFF08storage \u5229\u7528\u4E0D\u53EF\uFF09\u3002\u30B3\u30FC\u30EB\u30D0\u30C3\u30AF\u3067\u306E CSRF \u691C\u8A3C\u304C\u5931\u6557\u3057\u307E\u3059"
+      );
+    }
     const redirectUri = resolvedRedirectUri ?? window.location.origin + window.location.pathname;
     const params = new URLSearchParams({
       response_type: "code",
@@ -2316,7 +2379,8 @@ var FFID_ERROR_CODES = {
   TOKEN_EXCHANGE_ERROR: "TOKEN_EXCHANGE_ERROR",
   TOKEN_REFRESH_ERROR: "TOKEN_REFRESH_ERROR",
   NO_TOKENS: "NO_TOKENS",
-  TOKEN_VERIFICATION_ERROR: "TOKEN_VERIFICATION_ERROR"
+  TOKEN_VERIFICATION_ERROR: "TOKEN_VERIFICATION_ERROR",
+  STATE_MISMATCH_ERROR: "STATE_MISMATCH_ERROR"
 };
 var EXT_CHECK_ENDPOINT = "/api/v1/subscriptions/ext/check";
 var DEFAULT_ALLOW_GRACE = true;

package/dist/server/index.d.cts

@@ -1,5 +1,5 @@
-import { F as FFIDLogger, a as FFIDError, b as FFIDCacheAdapter, c as FFIDVerifyAccessTokenOptions, d as FFIDApiResponse, e as FFIDOAuthUserInfo } from '../ffid-client-Dx4oc4Cw.cjs';
-export { f as FFIDAddMemberParams, g as FFIDAddMemberRequest, h as FFIDAddMemberResponse, i as FFIDAssignableMemberRole, j as FFIDCacheConfig, k as FFIDClient, l as FFIDConfig, m as FFIDListMembersResponse, n as FFIDMemberRole, o as FFIDOrganization, p as FFIDOrganizationMember, q as FFIDOtpSendResponse, r as FFIDOtpVerifyResponse, s as FFIDPasswordResetConfirmResponse, t as FFIDPasswordResetResponse, u as FFIDPasswordResetVerifyResponse, v as FFIDProfileCallOptions, w as FFIDRemoveMemberResponse, x as FFIDResetSessionResponse, y as FFIDSubscription, z as FFIDUpdateMemberRoleResponse, A as FFIDUpdateUserProfileRequest, B as FFIDUser, C as FFIDUserProfile, T as TokenData, D as TokenStore, E as createFFIDClient, G as createTokenStore } from '../ffid-client-Dx4oc4Cw.cjs';
+import { F as FFIDLogger, a as FFIDError, b as FFIDCacheAdapter, c as FFIDVerifyAccessTokenOptions, d as FFIDApiResponse, e as FFIDOAuthUserInfo } from '../ffid-client-C3K3sAqq.cjs';
+export { f as FFIDAddMemberParams, g as FFIDAddMemberRequest, h as FFIDAddMemberResponse, i as FFIDAssignableMemberRole, j as FFIDCacheConfig, k as FFIDClient, l as FFIDConfig, m as FFIDListMembersResponse, n as FFIDMemberRole, o as FFIDOrganization, p as FFIDOrganizationMember, q as FFIDOtpSendResponse, r as FFIDOtpVerifyResponse, s as FFIDPasswordResetConfirmResponse, t as FFIDPasswordResetResponse, u as FFIDPasswordResetVerifyResponse, v as FFIDProfileCallOptions, w as FFIDRemoveMemberResponse, x as FFIDResetSessionResponse, y as FFIDSubscription, z as FFIDUpdateMemberRoleResponse, A as FFIDUpdateUserProfileRequest, B as FFIDUser, C as FFIDUserProfile, T as TokenData, D as TokenStore, E as createFFIDClient, G as createTokenStore } from '../ffid-client-C3K3sAqq.cjs';
 export { D as DEFAULT_API_BASE_URL, a as DEFAULT_OAUTH_SCOPES } from '../constants-D61jqRIO.cjs';
 import { z } from 'zod';
 import '../types-BeVl-z12.cjs';

package/dist/server/index.d.ts

@@ -1,5 +1,5 @@
-import { F as FFIDLogger, a as FFIDError, b as FFIDCacheAdapter, c as FFIDVerifyAccessTokenOptions, d as FFIDApiResponse, e as FFIDOAuthUserInfo } from '../ffid-client-5IprSUVR.js';
-export { f as FFIDAddMemberParams, g as FFIDAddMemberRequest, h as FFIDAddMemberResponse, i as FFIDAssignableMemberRole, j as FFIDCacheConfig, k as FFIDClient, l as FFIDConfig, m as FFIDListMembersResponse, n as FFIDMemberRole, o as FFIDOrganization, p as FFIDOrganizationMember, q as FFIDOtpSendResponse, r as FFIDOtpVerifyResponse, s as FFIDPasswordResetConfirmResponse, t as FFIDPasswordResetResponse, u as FFIDPasswordResetVerifyResponse, v as FFIDProfileCallOptions, w as FFIDRemoveMemberResponse, x as FFIDResetSessionResponse, y as FFIDSubscription, z as FFIDUpdateMemberRoleResponse, A as FFIDUpdateUserProfileRequest, B as FFIDUser, C as FFIDUserProfile, T as TokenData, D as TokenStore, E as createFFIDClient, G as createTokenStore } from '../ffid-client-5IprSUVR.js';
+import { F as FFIDLogger, a as FFIDError, b as FFIDCacheAdapter, c as FFIDVerifyAccessTokenOptions, d as FFIDApiResponse, e as FFIDOAuthUserInfo } from '../ffid-client-BG0Qr86U.js';
+export { f as FFIDAddMemberParams, g as FFIDAddMemberRequest, h as FFIDAddMemberResponse, i as FFIDAssignableMemberRole, j as FFIDCacheConfig, k as FFIDClient, l as FFIDConfig, m as FFIDListMembersResponse, n as FFIDMemberRole, o as FFIDOrganization, p as FFIDOrganizationMember, q as FFIDOtpSendResponse, r as FFIDOtpVerifyResponse, s as FFIDPasswordResetConfirmResponse, t as FFIDPasswordResetResponse, u as FFIDPasswordResetVerifyResponse, v as FFIDProfileCallOptions, w as FFIDRemoveMemberResponse, x as FFIDResetSessionResponse, y as FFIDSubscription, z as FFIDUpdateMemberRoleResponse, A as FFIDUpdateUserProfileRequest, B as FFIDUser, C as FFIDUserProfile, T as TokenData, D as TokenStore, E as createFFIDClient, G as createTokenStore } from '../ffid-client-BG0Qr86U.js';
 export { D as DEFAULT_API_BASE_URL, a as DEFAULT_OAUTH_SCOPES } from '../constants-D61jqRIO.js';
 import { z } from 'zod';
 import '../types-BeVl-z12.js';

package/dist/server/index.js

@@ -118,6 +118,9 @@ function normalizeUserinfo(raw) {
   return {
     sub: raw.sub,
     email: raw.email,
+    // #3791: undefined → undefined を保つ（false に丸めない）。古い FFID は wire に
+    // 含めないため、consumer は undefined を「未確認」ではなく「不明」として扱える。
+    emailVerified: raw.email_verified,
     name: raw.name,
     picture: raw.picture,
     companyName: raw.company_name ?? null,
@@ -373,6 +376,9 @@ function createVerifyAccessToken(deps) {
     const base = {
       sub: introspectResponse.sub,
       email: introspectResponse.email ?? null,
+      // #3791: preserve undefined (do NOT coerce to false) so introspect-strategy
+      // callers can distinguish "verified" / "not verified" / "older server".
+      email_verified: introspectResponse.email_verified,
       name: introspectResponse.name ?? null,
       picture: introspectResponse.picture ?? null,
       company_name: introspectResponse.company_name ?? null,
@@ -928,7 +934,7 @@ function createProfileMethods(deps) {
 }
 
 // src/client/version-check.ts
-var SDK_VERSION = "5.12.0";
+var SDK_VERSION = "5.13.0";
 var SDK_USER_AGENT = `FFID-SDK/${SDK_VERSION} (TypeScript)`;
 var SDK_VERSION_HEADER = "X-FFID-SDK-Version";
 function sdkHeaders() {
@@ -1000,9 +1006,20 @@ function createOAuthTokenMethods(deps) {
     logger,
     errorCodes
   } = deps;
-  async function exchangeCodeForTokens(code, codeVerifier) {
+  async function exchangeCodeForTokens(code, codeVerifier, opts) {
     const url = `${baseUrl}${OAUTH_TOKEN_ENDPOINT}`;
     logger.debug("Exchanging code for tokens:", url);
+    if (opts?.expectedState !== void 0 || opts?.actualState !== void 0) {
+      if (opts?.expectedState !== opts?.actualState) {
+        logger.error("Token exchange aborted: OAuth state mismatch or omitted (possible CSRF)");
+        return {
+          error: {
+            code: errorCodes.STATE_MISMATCH_ERROR,
+            message: "OAuth state \u304C\u4E00\u81F4\u3057\u307E\u305B\u3093\u3002CSRF \u306E\u53EF\u80FD\u6027\u304C\u3042\u308B\u305F\u3081\u8A8D\u8A3C\u3092\u4E2D\u6B62\u3057\u307E\u3057\u305F"
+          }
+        };
+      }
+    }
     const effectiveRedirectUri = resolvedRedirectUri ?? (typeof window !== "undefined" ? window.location.origin + window.location.pathname : null);
     if (!effectiveRedirectUri) {
       logger.error("redirectUri is required for token exchange in SSR environments. Set config.redirectUri explicitly.");
@@ -1447,6 +1464,46 @@ function base64UrlEncode(buffer) {
   return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
 
+// src/auth/state.ts
+var STATE_STORAGE_KEY = "ffid_oauth_state";
+var STATE_FALLBACK_STORAGE_KEY = "ffid_oauth_state_fb";
+var STATE_FALLBACK_TIMESTAMP_KEY = "ffid_oauth_state_fb_ts";
+function storeState(state, logger) {
+  if (typeof window === "undefined") {
+    logger?.warn("storeState: storage is not available in SSR context");
+    return false;
+  }
+  let sessionStored = false;
+  try {
+    window.sessionStorage.setItem(STATE_STORAGE_KEY, state);
+    sessionStored = true;
+  } catch (error) {
+    logger?.warn("storeState: sessionStorage \u3078\u306E\u4FDD\u5B58\u306B\u5931\u6557\u3057\u307E\u3057\u305F:", error);
+  }
+  let localStored = false;
+  try {
+    window.localStorage.setItem(STATE_FALLBACK_STORAGE_KEY, state);
+    window.localStorage.setItem(STATE_FALLBACK_TIMESTAMP_KEY, String(Date.now()));
+    localStored = true;
+  } catch (error) {
+    logger?.warn("storeState: localStorage fallback \u3078\u306E\u4FDD\u5B58\u306B\u5931\u6557\u3057\u307E\u3057\u305F:", error);
+  }
+  return sessionStored || localStored;
+}
+function cleanupStateStorage(logger) {
+  try {
+    window.sessionStorage.removeItem(STATE_STORAGE_KEY);
+  } catch (error) {
+    logger?.warn("retrieveState: sessionStorage \u306E\u30AF\u30EA\u30FC\u30F3\u30A2\u30C3\u30D7\u306B\u5931\u6557\u3057\u307E\u3057\u305F:", error);
+  }
+  try {
+    window.localStorage.removeItem(STATE_FALLBACK_STORAGE_KEY);
+    window.localStorage.removeItem(STATE_FALLBACK_TIMESTAMP_KEY);
+  } catch (error) {
+    logger?.warn("retrieveState: localStorage \u306E\u30AF\u30EA\u30FC\u30F3\u30A2\u30C3\u30D7\u306B\u5931\u6557\u3057\u307E\u3057\u305F:", error);
+  }
+}
+
 // src/client/redirect.ts
 var OAUTH_AUTHORIZE_ENDPOINT = "/api/v1/oauth/authorize";
 var AUTH_LOGOUT_ENDPOINT = "/api/v1/auth/logout";
@@ -1578,6 +1635,7 @@ function createRedirectMethods(deps) {
     const recentCount = getRecentRedirectCount(authorizeKey, now, logger);
     if (recentCount >= REDIRECT_LOOP_THRESHOLD) {
       cleanupVerifierStorage(logger);
+      cleanupStateStorage(logger);
       logger.warn("[FFID SDK] redirect loop detected \u2014 \u81EA\u52D5\u30EA\u30C0\u30A4\u30EC\u30AF\u30C8\u3092\u505C\u6B62\u3057\u307E\u3057\u305F", {
         authorizeKey,
         recentCount,
@@ -1601,6 +1659,11 @@ function createRedirectMethods(deps) {
       return { success: false, error: errorMessage };
     }
     const state = generateRandomState();
+    if (!storeState(state, logger)) {
+      logger.error(
+        "redirectToAuthorize: OAuth state \u3092\u4FDD\u5B58\u3067\u304D\u307E\u305B\u3093\u3067\u3057\u305F\uFF08storage \u5229\u7528\u4E0D\u53EF\uFF09\u3002\u30B3\u30FC\u30EB\u30D0\u30C3\u30AF\u3067\u306E CSRF \u691C\u8A3C\u304C\u5931\u6557\u3057\u307E\u3059"
+      );
+    }
     const redirectUri = resolvedRedirectUri ?? window.location.origin + window.location.pathname;
     const params = new URLSearchParams({
       response_type: "code",
@@ -2315,7 +2378,8 @@ var FFID_ERROR_CODES = {
   TOKEN_EXCHANGE_ERROR: "TOKEN_EXCHANGE_ERROR",
   TOKEN_REFRESH_ERROR: "TOKEN_REFRESH_ERROR",
   NO_TOKENS: "NO_TOKENS",
-  TOKEN_VERIFICATION_ERROR: "TOKEN_VERIFICATION_ERROR"
+  TOKEN_VERIFICATION_ERROR: "TOKEN_VERIFICATION_ERROR",
+  STATE_MISMATCH_ERROR: "STATE_MISMATCH_ERROR"
 };
 var EXT_CHECK_ENDPOINT = "/api/v1/subscriptions/ext/check";
 var DEFAULT_ALLOW_GRACE = true;

package/dist/server/test/index.d.cts

@@ -1,4 +1,4 @@
-import { k as FFIDClient, e as FFIDOAuthUserInfo } from '../../ffid-client-Dx4oc4Cw.cjs';
+import { k as FFIDClient, e as FFIDOAuthUserInfo } from '../../ffid-client-C3K3sAqq.cjs';
 import '../../types-BeVl-z12.cjs';
 
 /**

package/dist/server/test/index.d.ts

@@ -1,4 +1,4 @@
-import { k as FFIDClient, e as FFIDOAuthUserInfo } from '../../ffid-client-5IprSUVR.js';
+import { k as FFIDClient, e as FFIDOAuthUserInfo } from '../../ffid-client-BG0Qr86U.js';
 import '../../types-BeVl-z12.js';
 
 /**