tenneo-auth-plugin 1.0.0 → 1.0.3

package/dist/index.d.mts

@@ -6,29 +6,27 @@ import React from 'react';
 declare function bootstrap(): Promise<void>;
 
 /**
- * Logout functionality.
- * Sets force_login, clears auth storage; does not redirect (bootstrap handles that).
+ * Logout: idempotent, host-driven config, no fragile host_config snapshot/restore.
  *
- * This module is hardened for:
- * - Multi-tab race safety (timestamp-based lock)
- * - Proper server logout validation
- * - Scoped auth storage cleanup
- * - Watcher lifecycle correctness
- * - CSRF protection (when host app provides a token)
+ * - Watchers suspended during teardown to avoid bootstrap races
+ * - Server logout: POST only (no unsafe GET fallback)
+ * - Local state always cleared even if server fails
+ * - Storage cache refreshed from current runtime config (memory/host), never a stale snapshot
  */
 interface LogoutResponse {
     success?: boolean;
     message?: string;
     logout?: boolean;
 }
-/**
- * Public logout API – keeps signature/backward-compatibility.
- */
-declare function logout(tenantKey?: string): Promise<{
+type LogoutResult = {
     success: boolean;
     message: string;
     serverResponse?: LogoutResponse;
-}>;
+};
+/**
+ * Idempotent logout: coalesces concurrent calls in the same JS realm; cross-tab deduped via short lock.
+ */
+declare function logout(tenantKey?: string): Promise<LogoutResult>;
 
 /**
  * Domain types for the authentication gateway plugin.
@@ -221,8 +219,13 @@ interface SDKConfig {
     authServerUrl?: string;
     /** Callback/redirect URL (full URL). */
     callbackUrl?: string;
+    /** Alias some hosts use for OAuth redirect URI (same as callbackUrl). */
+    redirectUri?: string;
     /** Optional tenant code/key (used for tenant resolution). */
     tenantCode?: string;
+    tenantKey?: string;
+    /** Optional app identifier (storage namespacing). */
+    appId?: string;
     /** Optional runtime identifiers (may be returned from tenant API). */
     clientId?: string;
     tenantId?: string;
@@ -236,8 +239,73 @@ interface ResolvedConfig {
     authServerUrl: string;
     callbackUrl: string;
     clientCode: string;
+    tenantCode: string;
+    appId: string;
+    /** OAuth client id (may match clientCode / public client). */
+    clientId: string;
+    /** Tenant id from tenant resolution API when available. */
+    tenantId: string;
 }
-type ResolvedHostConfig = ResolvedConfig;
+
+/**
+ * Host-aware config resolution: memory → host bridge (window / provider) → storage cache (fallback).
+ * Does not import application/storage barrel to avoid circular deps — uses storage/kv only.
+ */
+
+type ConfigLayerSource = 'override' | 'memory' | 'host_bridge' | 'storage_cache';
+declare global {
+    interface Window {
+        /** Optional host-injected auth config (runtime). Lowest priority vs setConfig memory, above storage cache. */
+        __TENNEO_AUTH_HOST__?: Partial<SDKConfig>;
+    }
+}
+declare function setConfig(overrides: HostConfigOverride): void;
+declare function setHostConfigProvider(fn: (() => Partial<SDKConfig> | null | undefined) | null): void;
+interface FieldSourceMap {
+    tenantCode?: ConfigLayerSource;
+    tenantKey?: ConfigLayerSource;
+    apiBaseUrl?: ConfigLayerSource;
+    authServerUrl?: ConfigLayerSource;
+    callbackUrl?: ConfigLayerSource;
+    clientCode?: ConfigLayerSource;
+    clientId?: ConfigLayerSource;
+    tenantId?: ConfigLayerSource;
+    appId?: ConfigLayerSource;
+}
+/**
+ * Per-field source for debugging (first layer that supplied a non-empty value).
+ */
+declare function getConfigFieldSources(overrides?: HostConfigOverride): FieldSourceMap;
+declare function getEffectiveTenantCode(overrides?: HostConfigOverride): string;
+/** @alias getEffectiveTenantCode — tenant_key / tenant_code / clientCode from resolved config */
+declare const getEffectiveTenantKey: typeof getEffectiveTenantCode;
+interface GetAuthConfigOptions {
+    /** When true, throws if required OAuth / tenant fields are missing. */
+    strict?: boolean;
+    overrides?: HostConfigOverride;
+}
+declare class AuthConfigError extends Error {
+    readonly code = "AUTH_CONFIG_MISSING";
+    readonly missing: string[];
+    constructor(missing: string[], message?: string);
+}
+declare function resolveConfig(overrides?: HostConfigOverride): ResolvedConfig;
+/**
+ * Persist a non-authoritative copy for early readers (bootstrap before React).
+ * Never use as sole source of truth — memory/host win at resolve time.
+ */
+/**
+ * After logout or host-driven updates: persist a cache snapshot from current resolved SDK config (non-empty fields only).
+ */
+declare function syncHostConfigCacheFromMemory(): void;
+declare function writeHostConfigCache(partial: HostConfigOverride): void;
+/**
+ * Host entrypoint: merge into memory and optionally refresh storage cache.
+ */
+declare function initPlugin(config: HostConfigOverride, opts?: {
+    syncStorageCache?: boolean;
+}): void;
+declare function logConfigResolutionDebug(context: string, overrides?: HostConfigOverride): void;
 
 /**
  * OAuth constants and storage keys. No config resolution — pure constants.
@@ -262,23 +330,24 @@ declare const STORAGE_KEYS: {
     readonly expiresAt: "tenneo_auth_expires_at";
 };
 
-/**
- * Config: minimal host-driven config store + facade.
- *
- * No "internal" or "runtime" config separation.
- * Everything comes from the host app via `setConfig()` / `AuthProvider` props.
- */
-
-declare function resolveConfig(overrides?: HostConfigOverride): ResolvedConfig;
+/** Resolved config; pass `{ strict: true }` to fail fast if OAuth fields are missing. */
+declare function getAuthConfig(options?: GetAuthConfigOptions): ResolvedConfig;
+/** Fail fast when authServerUrl, callbackUrl, or tenant are missing. */
+declare function requireAuthConfig(overrides?: HostConfigOverride): ResolvedConfig;
 declare function getConfig(): ResolvedConfig;
-declare function setConfig(overrides: HostConfigOverride): void;
 declare const Config: {
     readonly getApiBaseUrl: () => string;
     readonly getAuthServerUrl: () => string;
     readonly getClientCode: () => string;
     readonly getRedirectUri: () => string;
-    readonly getAll: () => ResolvedHostConfig;
+    readonly getAll: () => ResolvedConfig;
 };
+/**
+ * Apply tenant switch in runtime config (memory + optional cache). Does not read stale snapshots.
+ */
+declare function applyRuntimeTenantSwitch(tenantKey: string, opts?: {
+    syncStorageCache?: boolean;
+}): void;
 
 /**
  * React Context Provider for authentication state (FINAL)
@@ -511,6 +580,21 @@ declare function startCookieWatcher(): void;
 declare function stopCookieWatcher(): void;
 declare function resetCookieWatcher(): void;
 
+/**
+ * Storage watcher to detect manual storage clears and restart auth flow.
+ * Infrastructure layer: uses storage and callback; application sets callback to bootstrap.
+ */
+declare function startStorageWatcher(): void;
+declare function stopStorageWatcher(): void;
+
+/**
+ * Suppress watcher side effects during intentional auth teardown (e.g. logout).
+ * Deterministic: set before storage/cookie mutation, clear after cleanup completes.
+ */
+declare function suspendWatchers(): number;
+declare function resumeWatchers(expectedGen?: number): void;
+declare function areWatchersSuspended(): boolean;
+
 /**
  * Structured auth event emitter for observability and audit.
  */
@@ -539,4 +623,4 @@ type AuthEventHandler = (payload?: AuthEventPayload) => void;
 declare function emitAuthEvent(event: AuthEventName, payload?: AuthEventPayload): void;
 declare function subscribeAuthEvent(event: AuthEventName | '*', handler: AuthEventHandler): () => void;
 
-export { AuthCallback, type AuthContextValue, type AuthEngine, type AuthEngineConfig, type AuthEngineState, type AuthEventHandler, type AuthEventName, AuthEventNames, type AuthEventPayload, AuthProvider, type AuthRuntime, type AuthState, type AuthStateListener, type AuthStrategy, type AuthTokens, Config, type ConfigProvider, type CookieClearer, type CurrentUrl, type EnvConfig, type HostConfigOverride, type Logger, OAUTH_CONSTANTS, ProtectedRoute, type ResolvedConfig, type SDKConfig, STORAGE_KEYS, STORAGE_KEY_PREFIX, SanitizedError, type StorageAdapter, type StorageNamespace, type TenantConfig, type TenantResolver, type TokenResponse, type TokenStorageAdapter, type Unsubscribe, type UrlProvider, bootstrap, buildStorageKey, createAuthEngine, createCookieStorageAdapter, createMemoryStorageAdapter, createOAuth2PkceStrategy, createSecureSessionStorageAdapter, emitAuthEvent, enforceHttps, ensureValidAccessToken, extractTenantKey, getAccessToken$1 as getAccessToken, getAuthRuntime, getConfig, getStorageAdapter, getStorageNamespace, getAccessToken as getStoredAccessToken, isAccessTokenExpired, isCallbackUrl, logout, refreshAccessToken, resetCookieWatcher, resolveConfig, resolveTenant, sanitizeErrorMessage, setAuthRuntime, setConfig, setStorageContext, startCookieWatcher, stopCookieWatcher, subscribeAuthEvent, useAuth, useAuthContext, useAuthInit };
+export { AuthCallback, AuthConfigError, type AuthContextValue, type AuthEngine, type AuthEngineConfig, type AuthEngineState, type AuthEventHandler, type AuthEventName, AuthEventNames, type AuthEventPayload, AuthProvider, type AuthRuntime, type AuthState, type AuthStateListener, type AuthStrategy, type AuthTokens, Config, type ConfigLayerSource, type ConfigProvider, type CookieClearer, type CurrentUrl, type EnvConfig, type FieldSourceMap, type GetAuthConfigOptions, type HostConfigOverride, type Logger, OAUTH_CONSTANTS, ProtectedRoute, type ResolvedConfig, type SDKConfig, STORAGE_KEYS, STORAGE_KEY_PREFIX, SanitizedError, type StorageAdapter, type StorageNamespace, type TenantConfig, type TenantResolver, type TokenResponse, type TokenStorageAdapter, type Unsubscribe, type UrlProvider, applyRuntimeTenantSwitch, areWatchersSuspended, bootstrap, buildStorageKey, createAuthEngine, createCookieStorageAdapter, createMemoryStorageAdapter, createOAuth2PkceStrategy, createSecureSessionStorageAdapter, emitAuthEvent, enforceHttps, ensureValidAccessToken, extractTenantKey, getAccessToken$1 as getAccessToken, getAuthConfig, getAuthRuntime, getConfig, getConfigFieldSources, getEffectiveTenantCode, getEffectiveTenantKey, getStorageAdapter, getStorageNamespace, getAccessToken as getStoredAccessToken, initPlugin, isAccessTokenExpired, isCallbackUrl, logConfigResolutionDebug, logout, refreshAccessToken, requireAuthConfig, resetCookieWatcher, resolveConfig, resolveTenant, resumeWatchers, sanitizeErrorMessage, setAuthRuntime, setConfig, setHostConfigProvider, setStorageContext, startCookieWatcher, startStorageWatcher, stopCookieWatcher, stopStorageWatcher, subscribeAuthEvent, suspendWatchers, syncHostConfigCacheFromMemory, useAuth, useAuthContext, useAuthInit, writeHostConfigCache };

package/dist/index.d.ts

@@ -6,29 +6,27 @@ import React from 'react';
 declare function bootstrap(): Promise<void>;
 
 /**
- * Logout functionality.
- * Sets force_login, clears auth storage; does not redirect (bootstrap handles that).
+ * Logout: idempotent, host-driven config, no fragile host_config snapshot/restore.
  *
- * This module is hardened for:
- * - Multi-tab race safety (timestamp-based lock)
- * - Proper server logout validation
- * - Scoped auth storage cleanup
- * - Watcher lifecycle correctness
- * - CSRF protection (when host app provides a token)
+ * - Watchers suspended during teardown to avoid bootstrap races
+ * - Server logout: POST only (no unsafe GET fallback)
+ * - Local state always cleared even if server fails
+ * - Storage cache refreshed from current runtime config (memory/host), never a stale snapshot
  */
 interface LogoutResponse {
     success?: boolean;
     message?: string;
     logout?: boolean;
 }
-/**
- * Public logout API – keeps signature/backward-compatibility.
- */
-declare function logout(tenantKey?: string): Promise<{
+type LogoutResult = {
     success: boolean;
     message: string;
     serverResponse?: LogoutResponse;
-}>;
+};
+/**
+ * Idempotent logout: coalesces concurrent calls in the same JS realm; cross-tab deduped via short lock.
+ */
+declare function logout(tenantKey?: string): Promise<LogoutResult>;
 
 /**
  * Domain types for the authentication gateway plugin.
@@ -221,8 +219,13 @@ interface SDKConfig {
     authServerUrl?: string;
     /** Callback/redirect URL (full URL). */
     callbackUrl?: string;
+    /** Alias some hosts use for OAuth redirect URI (same as callbackUrl). */
+    redirectUri?: string;
     /** Optional tenant code/key (used for tenant resolution). */
     tenantCode?: string;
+    tenantKey?: string;
+    /** Optional app identifier (storage namespacing). */
+    appId?: string;
     /** Optional runtime identifiers (may be returned from tenant API). */
     clientId?: string;
     tenantId?: string;
@@ -236,8 +239,73 @@ interface ResolvedConfig {
     authServerUrl: string;
     callbackUrl: string;
     clientCode: string;
+    tenantCode: string;
+    appId: string;
+    /** OAuth client id (may match clientCode / public client). */
+    clientId: string;
+    /** Tenant id from tenant resolution API when available. */
+    tenantId: string;
 }
-type ResolvedHostConfig = ResolvedConfig;
+
+/**
+ * Host-aware config resolution: memory → host bridge (window / provider) → storage cache (fallback).
+ * Does not import application/storage barrel to avoid circular deps — uses storage/kv only.
+ */
+
+type ConfigLayerSource = 'override' | 'memory' | 'host_bridge' | 'storage_cache';
+declare global {
+    interface Window {
+        /** Optional host-injected auth config (runtime). Lowest priority vs setConfig memory, above storage cache. */
+        __TENNEO_AUTH_HOST__?: Partial<SDKConfig>;
+    }
+}
+declare function setConfig(overrides: HostConfigOverride): void;
+declare function setHostConfigProvider(fn: (() => Partial<SDKConfig> | null | undefined) | null): void;
+interface FieldSourceMap {
+    tenantCode?: ConfigLayerSource;
+    tenantKey?: ConfigLayerSource;
+    apiBaseUrl?: ConfigLayerSource;
+    authServerUrl?: ConfigLayerSource;
+    callbackUrl?: ConfigLayerSource;
+    clientCode?: ConfigLayerSource;
+    clientId?: ConfigLayerSource;
+    tenantId?: ConfigLayerSource;
+    appId?: ConfigLayerSource;
+}
+/**
+ * Per-field source for debugging (first layer that supplied a non-empty value).
+ */
+declare function getConfigFieldSources(overrides?: HostConfigOverride): FieldSourceMap;
+declare function getEffectiveTenantCode(overrides?: HostConfigOverride): string;
+/** @alias getEffectiveTenantCode — tenant_key / tenant_code / clientCode from resolved config */
+declare const getEffectiveTenantKey: typeof getEffectiveTenantCode;
+interface GetAuthConfigOptions {
+    /** When true, throws if required OAuth / tenant fields are missing. */
+    strict?: boolean;
+    overrides?: HostConfigOverride;
+}
+declare class AuthConfigError extends Error {
+    readonly code = "AUTH_CONFIG_MISSING";
+    readonly missing: string[];
+    constructor(missing: string[], message?: string);
+}
+declare function resolveConfig(overrides?: HostConfigOverride): ResolvedConfig;
+/**
+ * Persist a non-authoritative copy for early readers (bootstrap before React).
+ * Never use as sole source of truth — memory/host win at resolve time.
+ */
+/**
+ * After logout or host-driven updates: persist a cache snapshot from current resolved SDK config (non-empty fields only).
+ */
+declare function syncHostConfigCacheFromMemory(): void;
+declare function writeHostConfigCache(partial: HostConfigOverride): void;
+/**
+ * Host entrypoint: merge into memory and optionally refresh storage cache.
+ */
+declare function initPlugin(config: HostConfigOverride, opts?: {
+    syncStorageCache?: boolean;
+}): void;
+declare function logConfigResolutionDebug(context: string, overrides?: HostConfigOverride): void;
 
 /**
  * OAuth constants and storage keys. No config resolution — pure constants.
@@ -262,23 +330,24 @@ declare const STORAGE_KEYS: {
     readonly expiresAt: "tenneo_auth_expires_at";
 };
 
-/**
- * Config: minimal host-driven config store + facade.
- *
- * No "internal" or "runtime" config separation.
- * Everything comes from the host app via `setConfig()` / `AuthProvider` props.
- */
-
-declare function resolveConfig(overrides?: HostConfigOverride): ResolvedConfig;
+/** Resolved config; pass `{ strict: true }` to fail fast if OAuth fields are missing. */
+declare function getAuthConfig(options?: GetAuthConfigOptions): ResolvedConfig;
+/** Fail fast when authServerUrl, callbackUrl, or tenant are missing. */
+declare function requireAuthConfig(overrides?: HostConfigOverride): ResolvedConfig;
 declare function getConfig(): ResolvedConfig;
-declare function setConfig(overrides: HostConfigOverride): void;
 declare const Config: {
     readonly getApiBaseUrl: () => string;
     readonly getAuthServerUrl: () => string;
     readonly getClientCode: () => string;
     readonly getRedirectUri: () => string;
-    readonly getAll: () => ResolvedHostConfig;
+    readonly getAll: () => ResolvedConfig;
 };
+/**
+ * Apply tenant switch in runtime config (memory + optional cache). Does not read stale snapshots.
+ */
+declare function applyRuntimeTenantSwitch(tenantKey: string, opts?: {
+    syncStorageCache?: boolean;
+}): void;
 
 /**
  * React Context Provider for authentication state (FINAL)
@@ -511,6 +580,21 @@ declare function startCookieWatcher(): void;
 declare function stopCookieWatcher(): void;
 declare function resetCookieWatcher(): void;
 
+/**
+ * Storage watcher to detect manual storage clears and restart auth flow.
+ * Infrastructure layer: uses storage and callback; application sets callback to bootstrap.
+ */
+declare function startStorageWatcher(): void;
+declare function stopStorageWatcher(): void;
+
+/**
+ * Suppress watcher side effects during intentional auth teardown (e.g. logout).
+ * Deterministic: set before storage/cookie mutation, clear after cleanup completes.
+ */
+declare function suspendWatchers(): number;
+declare function resumeWatchers(expectedGen?: number): void;
+declare function areWatchersSuspended(): boolean;
+
 /**
  * Structured auth event emitter for observability and audit.
  */
@@ -539,4 +623,4 @@ type AuthEventHandler = (payload?: AuthEventPayload) => void;
 declare function emitAuthEvent(event: AuthEventName, payload?: AuthEventPayload): void;
 declare function subscribeAuthEvent(event: AuthEventName | '*', handler: AuthEventHandler): () => void;
 
-export { AuthCallback, type AuthContextValue, type AuthEngine, type AuthEngineConfig, type AuthEngineState, type AuthEventHandler, type AuthEventName, AuthEventNames, type AuthEventPayload, AuthProvider, type AuthRuntime, type AuthState, type AuthStateListener, type AuthStrategy, type AuthTokens, Config, type ConfigProvider, type CookieClearer, type CurrentUrl, type EnvConfig, type HostConfigOverride, type Logger, OAUTH_CONSTANTS, ProtectedRoute, type ResolvedConfig, type SDKConfig, STORAGE_KEYS, STORAGE_KEY_PREFIX, SanitizedError, type StorageAdapter, type StorageNamespace, type TenantConfig, type TenantResolver, type TokenResponse, type TokenStorageAdapter, type Unsubscribe, type UrlProvider, bootstrap, buildStorageKey, createAuthEngine, createCookieStorageAdapter, createMemoryStorageAdapter, createOAuth2PkceStrategy, createSecureSessionStorageAdapter, emitAuthEvent, enforceHttps, ensureValidAccessToken, extractTenantKey, getAccessToken$1 as getAccessToken, getAuthRuntime, getConfig, getStorageAdapter, getStorageNamespace, getAccessToken as getStoredAccessToken, isAccessTokenExpired, isCallbackUrl, logout, refreshAccessToken, resetCookieWatcher, resolveConfig, resolveTenant, sanitizeErrorMessage, setAuthRuntime, setConfig, setStorageContext, startCookieWatcher, stopCookieWatcher, subscribeAuthEvent, useAuth, useAuthContext, useAuthInit };
+export { AuthCallback, AuthConfigError, type AuthContextValue, type AuthEngine, type AuthEngineConfig, type AuthEngineState, type AuthEventHandler, type AuthEventName, AuthEventNames, type AuthEventPayload, AuthProvider, type AuthRuntime, type AuthState, type AuthStateListener, type AuthStrategy, type AuthTokens, Config, type ConfigLayerSource, type ConfigProvider, type CookieClearer, type CurrentUrl, type EnvConfig, type FieldSourceMap, type GetAuthConfigOptions, type HostConfigOverride, type Logger, OAUTH_CONSTANTS, ProtectedRoute, type ResolvedConfig, type SDKConfig, STORAGE_KEYS, STORAGE_KEY_PREFIX, SanitizedError, type StorageAdapter, type StorageNamespace, type TenantConfig, type TenantResolver, type TokenResponse, type TokenStorageAdapter, type Unsubscribe, type UrlProvider, applyRuntimeTenantSwitch, areWatchersSuspended, bootstrap, buildStorageKey, createAuthEngine, createCookieStorageAdapter, createMemoryStorageAdapter, createOAuth2PkceStrategy, createSecureSessionStorageAdapter, emitAuthEvent, enforceHttps, ensureValidAccessToken, extractTenantKey, getAccessToken$1 as getAccessToken, getAuthConfig, getAuthRuntime, getConfig, getConfigFieldSources, getEffectiveTenantCode, getEffectiveTenantKey, getStorageAdapter, getStorageNamespace, getAccessToken as getStoredAccessToken, initPlugin, isAccessTokenExpired, isCallbackUrl, logConfigResolutionDebug, logout, refreshAccessToken, requireAuthConfig, resetCookieWatcher, resolveConfig, resolveTenant, resumeWatchers, sanitizeErrorMessage, setAuthRuntime, setConfig, setHostConfigProvider, setStorageContext, startCookieWatcher, startStorageWatcher, stopCookieWatcher, stopStorageWatcher, subscribeAuthEvent, suspendWatchers, syncHostConfigCacheFromMemory, useAuth, useAuthContext, useAuthInit, writeHostConfigCache };