tenneo-auth-plugin 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,558 @@
+import React from 'react';
+
+/**
+ * Public bootstrap API. Delegates to default engine.init() when set; otherwise runs runBootstrap().
+ */
+declare function bootstrap(): Promise<void>;
+
+/**
+ * Logout functionality.
+ * Sets force_login, clears auth storage; does not redirect (bootstrap handles that).
+ */
+interface LogoutResponse {
+    success?: boolean;
+    message?: string;
+    logout?: boolean;
+}
+declare function logout(tenantKey?: string): Promise<{
+    success: boolean;
+    message: string;
+    serverResponse?: LogoutResponse;
+}>;
+
+/**
+ * Domain types for the authentication gateway plugin.
+ * Pure types; no I/O.
+ */
+interface TenantConfig {
+    tenantId: string;
+    authServer: string;
+    tenantKey?: string;
+    client: {
+        clientId: string;
+        clientCode?: string;
+        redirectUri: string;
+        scopes: string;
+    };
+}
+interface TokenResponse {
+    access_token: string;
+    refresh_token: string;
+    expires_in: number;
+    token_type?: string;
+}
+interface AuthState {
+    isAuthenticated: boolean;
+    accessToken: string | null;
+    isLoading: boolean;
+    error: string | null;
+}
+interface AuthContextValue extends AuthState {
+    login: () => Promise<void>;
+    logout: () => Promise<void>;
+    refreshToken: () => Promise<string>;
+    getAccessToken: () => Promise<string>;
+    setTokens: (accessToken: string) => void;
+}
+interface EnvConfig {
+    authServerUrl: string;
+    clientId: string;
+    redirectUri: string;
+    tenantId: string;
+}
+
+/**
+ * OAuth2 PKCE token exchange and refresh.
+ * Strategy-owned implementation; uses API_AUTH_BASE_URL only.
+ */
+
+declare function refreshAccessToken(): Promise<string>;
+
+/**
+ * Token API: facades for public API.
+ * ensureValidAccessToken delegates to default engine when set; otherwise uses strategy refresh.
+ */
+
+declare function ensureValidAccessToken(): Promise<string>;
+declare function getAccessToken$1(): string | null;
+
+/**
+ * Storage adapter types for enterprise-grade token and key-value storage.
+ * SSR-safe: no direct window/document usage in interface.
+ */
+/**
+ * Shape of tokens stored by the adapter (used for getTokens/setTokens).
+ */
+interface AuthTokens {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: number;
+}
+/**
+ * Token-only storage contract (spec).
+ * Implementations must be SSR-safe: avoid window/document in method bodies
+ * or guard with typeof window !== 'undefined'.
+ */
+interface TokenStorageAdapter {
+    getTokens(): Promise<AuthTokens | null>;
+    setTokens(tokens: AuthTokens): Promise<void>;
+    clearTokens(): Promise<void>;
+}
+/**
+ * Optional key-value contract for config/flow flags.
+ * When implemented, allows replacing all sessionStorage/localStorage usage
+ * with a single injected adapter. Namespacing is applied by the adapter.
+ */
+interface KeyValueStorageAdapter {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+    clear(): Promise<void>;
+}
+/**
+ * Optional synchronous access for backward compatibility with existing sync APIs.
+ * When implemented, storage layer uses these so callers remain sync.
+ */
+interface SyncStorageAdapter {
+    getTokensSync?(): AuthTokens | null;
+    setTokensSync?(tokens: AuthTokens): void;
+    clearTokensSync?(): void;
+    getItemSync?(key: string): string | null;
+    setItemSync?(key: string, value: string): void;
+    removeItemSync?(key: string): void;
+    clearSync?(): void;
+}
+/**
+ * Full storage adapter: tokens + key-value.
+ * Default adapters implement this and SyncStorageAdapter for sync compatibility.
+ */
+type StorageAdapter = TokenStorageAdapter & KeyValueStorageAdapter & Partial<SyncStorageAdapter>;
+/**
+ * Namespace for storage keys: auth_${tenantId}_${appId}_*
+ * Used to isolate data per tenant and app (microfrontend support).
+ */
+interface StorageNamespace {
+    tenantId: string;
+    appId: string;
+}
+
+/**
+ * Storage key namespacing: auth_${tenantId}_${appId}_*
+ * Backward compatibility: when both tenantId and appId are empty, use dynamic prefix (from tenant code).
+ */
+
+/**
+ * Builds a namespaced storage key.
+ * - When tenantId and appId are both falsy: returns getStorageKeyPrefix() + suffix (tenant-code-based or default).
+ * - Otherwise: returns auth_${tenantId}_${appId}_${suffix}.
+ */
+declare function buildStorageKey(ns: StorageNamespace, suffix: string): string;
+
+/**
+ * Storage context: current adapter and namespace.
+ * Can be set via setStorageContext (legacy) or setAuthRuntime (full runtime).
+ * No window/document usage.
+ */
+
+declare function setStorageContext(adapter: StorageAdapter | null, namespace?: Partial<StorageNamespace>): void;
+declare function getStorageAdapter(): StorageAdapter | null;
+declare function getStorageNamespace(): StorageNamespace;
+
+/**
+ * In-memory storage adapter. SSR-safe; no window/document usage.
+ * Default for server-side or when no persistent storage is desired.
+ */
+
+declare function createMemoryStorageAdapter(namespace: StorageNamespace): StorageAdapter;
+
+/**
+ * Session storage adapter with namespaced keys. SSR-safe: guards all
+ * window/sessionStorage access with typeof window !== 'undefined'.
+ */
+
+declare function createSecureSessionStorageAdapter(namespace: StorageNamespace): StorageAdapter;
+
+/**
+ * Cookie-based storage adapter (HttpOnly-compatible abstraction).
+ * Tokens are stored in cookies; config/flow flags use cookies or fallback.
+ * SSR-safe: all document/window access guarded with typeof window !== 'undefined'.
+ *
+ * Note: True HttpOnly cookies must be set by the server. This adapter uses
+ * document.cookie for client-readable tokens when running in the browser,
+ * and can be replaced by a server-backed implementation for HttpOnly.
+ */
+
+declare function createCookieStorageAdapter(namespace: StorageNamespace, options?: {
+    cookiePrefix?: string;
+}): StorageAdapter;
+
+/**
+ * Storage API: adapter-based get/set/clear. No direct window/sessionStorage.
+ * Keys use dynamic prefix from tenant code (see prefix.ts).
+ */
+
+declare function getAccessToken(): string | null;
+declare function isAccessTokenExpired(): boolean;
+
+declare function useAuthContext(): AuthContextValue;
+
+/**
+ * React Context Provider for authentication state (FINAL)
+ */
+
+interface AuthProviderProps {
+    children: React.ReactNode;
+    autoInit?: boolean;
+    /** Tenant code from host app (used to resolve tenant via GET /api/tenant/v1/public/tenants/by-code/{tenantCode}). */
+    tenantCode?: string;
+    /** App id for storage namespacing (auth_${tenantId}_${appId}_*). */
+    appId?: string;
+    /** Optional storage adapter; default is SecureSessionStorageAdapter with namespacing. */
+    storageAdapter?: StorageAdapter | null;
+}
+/**
+ * AuthProvider – UI-facing auth state only
+ */
+declare function AuthProvider({ children, autoInit, tenantCode, appId, storageAdapter, }: AuthProviderProps): React.JSX.Element;
+
+interface AuthCallbackProps {
+    loginPath?: string;
+    successPath?: string;
+    homePath?: string;
+}
+declare function AuthCallback({ loginPath, successPath, homePath, }: AuthCallbackProps): React.JSX.Element;
+
+interface ProtectedRouteProps {
+    children: React.ReactNode;
+    fallback?: React.ReactNode;
+    autoLogin?: boolean;
+}
+declare function ProtectedRoute({ children, fallback, autoLogin, }: ProtectedRouteProps): React.JSX.Element;
+
+/**
+ * useAuth hook for accessing authentication state and methods
+ */
+
+/**
+ * Hook to access authentication state and methods
+ * @returns Authentication context value
+ */
+declare function useAuth(): AuthContextValue;
+
+/**
+ * useAuthInit hook
+ *
+ * RULES:
+ * - Only prevents parallel init calls
+ * - Does NOT block based on flags (bootstrap handles that)
+ */
+interface UseAuthInitResult {
+    isLoading: boolean;
+    error: string | null;
+    init: () => Promise<void>;
+}
+declare function useAuthInit(): UseAuthInitResult;
+
+/**
+ * Framework-agnostic runtime interfaces for the auth core.
+ * No React, window, or document dependencies.
+ */
+
+/** Current URL snapshot (replaces direct window.location usage in core). */
+interface CurrentUrl {
+    href: string;
+    origin: string;
+    pathname: string;
+    search: string;
+    hostname: string;
+}
+/** Logger interface – no console in core. */
+interface Logger {
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+    debug(message: string, meta?: Record<string, unknown>): void;
+}
+/** URL and navigation – replaces window.location / window.history in core. */
+interface UrlProvider {
+    getCurrentUrl(): CurrentUrl;
+    /** Full redirect (e.g. window.location.replace). */
+    redirect(url: string): void;
+    /** Soft replace (e.g. history.replaceState) without reload. */
+    replaceState(url: string): void;
+}
+/** Configuration – replaces direct Config / window.__APP_CONFIG__ in core. */
+interface ConfigProvider {
+    getApiBaseUrl(): string;
+    getAuthServerUrl(): string;
+    getRedirectUri(): string;
+    getClientId(): string;
+    getTenantId(): string;
+    getClientCode(): string;
+    getBasePath(): string;
+}
+/** Tenant resolution – replaces direct tenant API usage in core. */
+interface TenantResolver {
+    resolve(tenantKey: string): Promise<TenantConfig | null>;
+}
+/** Optional: clear cookies (e.g. on logout). Called by core when provided. */
+interface CookieClearer {
+    clearCookies(): void;
+}
+/**
+ * Auth runtime: all external dependencies injected.
+ * Core uses only this; no direct browser or framework APIs.
+ */
+interface AuthRuntime {
+    /** Required. Token + key-value storage. */
+    storageAdapter: StorageAdapter;
+    storageNamespace: StorageNamespace;
+    /** Required. No console.log in core. */
+    logger: Logger;
+    /** Required for redirects and URL checks. */
+    urlProvider: UrlProvider;
+    /** Required for OAuth and tenant config. */
+    configProvider: ConfigProvider;
+    /** Required for resolving tenant by key. */
+    tenantResolver: TenantResolver;
+    /** Optional. If not set, core will not clear cookies on logout. */
+    clearCookies?: CookieClearer;
+}
+
+/**
+ * Runtime context: single get/set for auth runtime.
+ * Core reads from here; host (e.g. React layer) sets before any core code runs.
+ */
+
+declare function setAuthRuntime(runtime: AuthRuntime | null): void;
+declare function getAuthRuntime(): AuthRuntime | null;
+
+/**
+ * Auth strategy interface for pluggable authentication.
+ * Engine and bootstrap depend on this interface, not concrete OAuth2 PKCE.
+ */
+
+interface AuthStrategy {
+    /** Start the auth flow (e.g. redirect to IdP). */
+    initiate(tenantConfig: TenantConfig): Promise<void>;
+    /** Handle OAuth callback (code exchange). Returns true if callback was handled. */
+    handleCallback(): Promise<boolean>;
+    /** Refresh access token. Returns new access token or throws. */
+    refresh(): Promise<string>;
+    /** Log out and clear session. */
+    logout(options?: {
+        tenantKey?: string;
+    }): Promise<void>;
+}
+
+/**
+ * Auth engine types. No React, no browser globals.
+ */
+
+type AuthEngineConfig = AuthRuntime & {
+    strategy?: AuthStrategy;
+};
+interface AuthEngineState {
+    status: 'idle' | 'loading' | 'authenticated' | 'unauthenticated' | 'error';
+    accessToken: string | null;
+    expiresAt: number | null;
+    error: string | null;
+}
+type AuthStateListener = (state: AuthEngineState) => void;
+type Unsubscribe = () => void;
+interface AuthEngine {
+    init(): Promise<void>;
+    login(): Promise<void>;
+    logout(options?: {
+        tenantKey?: string;
+    }): Promise<void>;
+    refresh(): Promise<string>;
+    getAccessToken(): Promise<string>;
+    handleCallback(): Promise<boolean>;
+    subscribe(listener: AuthStateListener): Unsubscribe;
+    getState(): AuthEngineState;
+}
+
+/**
+ * Creates the auth engine. No React, no direct browser usage.
+ */
+
+declare function createAuthEngine(config: AuthEngineConfig): AuthEngine;
+
+/**
+ * OAuth2 PKCE implementation of AuthStrategy.
+ * Wraps initiateAuthFlow, handleCallback, refreshAccessToken, and logout.
+ */
+
+declare function createOAuth2PkceStrategy(): AuthStrategy;
+
+/**
+ * Runtime-backed facade for domain tenant/callback helpers.
+ * Provides extractTenantKey(), isCallbackUrl(), isLocalhost() for public API and internal use.
+ * Uses runtime when set; falls back to window for backward compatibility.
+ */
+
+declare function extractTenantKey(): string | null;
+declare function isCallbackUrl(): boolean;
+
+/**
+ * Tenant resolution API client.
+ * Resolves tenant configuration via GET /api/tenant/v1/public/tenants/by-code/{tenantCode}.
+ */
+
+declare function resolveTenant(tenantKey: string): Promise<TenantConfig | null>;
+
+/**
+ * Configuration types.
+ * Internal: non-overridable (from .env). Runtime: overridable (env + window + setConfig).
+ *
+ * BASE URL SEPARATION (mandatory — do not mix):
+ * - API_TENANT_RESOLUTION_BASE_URL: Tenant resolution only.
+ * - API_AUTH_BASE_URL: Token operations only (exchange, refresh, logout).
+ * - AUTH_SERVER_URL: OpenID Connect authorization redirect only.
+ */
+interface InternalConfig {
+    API_TENANT_RESOLUTION_BASE_URL: string;
+    API_AUTH_BASE_URL: string;
+    AUTH_SERVER_URL: string;
+    DEFAULT_DOMAIN: string;
+}
+/** Single source of truth: .env (VITE_CLIENT_ID, VITE_TENANT_ID, VITE_CLIENTCODE). */
+interface RuntimeConfig {
+    CLIENT_ID: string;
+    TENANT_ID: string;
+    CLIENTCODE: string;
+}
+type ResolvedConfig = InternalConfig & RuntimeConfig;
+type SDKConfig = ResolvedConfig;
+interface RuntimeConfigOverrides {
+    basePath?: string;
+    redirectUri?: string;
+}
+type HostConfigOverride = Partial<RuntimeConfig> & Partial<RuntimeConfigOverrides>;
+/** Window __APP_CONFIG__ / __AUTH_CONFIG__ shape (clientId, tenantId, clientcode only). */
+interface HostRuntimeConfig {
+    clientId?: string;
+    tenantId?: string;
+    clientcode?: string;
+}
+/** Full resolved config output (internal URLs + runtime + derived redirectUri, basePath). */
+interface ResolvedHostConfig {
+    apiTenantResolutionBaseUrl: string;
+    apiAuthBaseUrl: string;
+    authServerUrl: string;
+    defaultDomain: string;
+    clientId: string;
+    tenantId: string;
+    clientCode: string;
+    redirectUri: string;
+    basePath: string;
+}
+
+/**
+ * OAuth constants and storage keys. No config resolution — pure constants.
+ */
+declare const OAUTH_CONSTANTS: {
+    readonly SCOPES: "openid profile email";
+    readonly RESPONSE_TYPE: "code";
+    readonly CODE_CHALLENGE_METHOD: "S256";
+    readonly TOKEN_GRANT_TYPE: "authorization_code";
+    readonly REFRESH_GRANT_TYPE: "refresh_token";
+};
+declare const STORAGE_KEY_PREFIX = "tenneo_auth_";
+declare const STORAGE_KEYS: {
+    readonly authServerUrl: "tenneo_auth_auth_server_url";
+    readonly clientId: "tenneo_auth_client_id";
+    readonly redirectUri: "tenneo_auth_redirect_uri";
+    readonly tenantId: "tenneo_auth_tenant_id";
+    readonly codeVerifier: "tenneo_auth_code_verifier";
+    readonly state: "tenneo_auth_state";
+    readonly accessToken: "tenneo_auth_access_token";
+    readonly refreshToken: "tenneo_auth_refresh_token";
+    readonly expiresAt: "tenneo_auth_expires_at";
+};
+
+/**
+ * Config: resolver + public Config facade.
+ * Resolution order: runtime overrides > window > env > defaults.
+ * Single source of truth: .env (see .env.example).
+ */
+
+declare global {
+    interface Window {
+        __APP_CONFIG__?: HostRuntimeConfig | {
+            [key: string]: unknown;
+        };
+        __AUTH_CONFIG__?: HostRuntimeConfig | {
+            [key: string]: unknown;
+        };
+    }
+}
+declare function resolveConfig(overrides?: HostConfigOverride): InternalConfig & RuntimeConfig;
+declare function getConfig(): InternalConfig & RuntimeConfig;
+declare function setConfig(overrides: HostConfigOverride): void;
+declare const Config: {
+    readonly getApiTenantResolutionBaseUrl: () => string;
+    readonly getApiAuthBaseUrl: () => string;
+    readonly getAuthServerUrl: () => string;
+    readonly getDefaultDomain: () => string;
+    readonly getClientId: () => string;
+    readonly getTenantId: () => string;
+    readonly getClientCode: () => string;
+    readonly getRedirectUri: () => string;
+    readonly getBasePath: () => string;
+    readonly hasRuntimeConfig: () => boolean;
+    readonly getAll: () => ResolvedHostConfig;
+};
+declare function getEnvConfig(): Promise<EnvConfig | null>;
+declare function hasEnvFallback(): boolean;
+
+/**
+ * Security and error utilities for authentication.
+ * Domain layer: sanitized errors and HTTPS enforcement.
+ */
+declare function enforceHttps(allowLocalhost?: boolean): void;
+declare function sanitizeErrorMessage(error: unknown, genericMessage: string): string;
+declare class SanitizedError extends Error {
+    readonly code: string;
+    readonly originalMessage?: string;
+    constructor(code: string, genericMessage: string, originalError?: unknown);
+}
+
+/**
+ * Cookie watcher to detect cookie deletion and clear session.
+ * Infrastructure layer: uses storage and callback; application sets callback to bootstrap.
+ */
+declare function startCookieWatcher(): void;
+declare function stopCookieWatcher(): void;
+declare function resetCookieWatcher(): void;
+
+/**
+ * Structured auth event emitter for observability and audit.
+ */
+declare const AuthEventNames: {
+    readonly LOGIN_STARTED: "LOGIN_STARTED";
+    readonly LOGIN_SUCCESS: "LOGIN_SUCCESS";
+    readonly LOGIN_FAILED: "LOGIN_FAILED";
+    readonly CALLBACK_SUCCESS: "CALLBACK_SUCCESS";
+    readonly CALLBACK_FAILED: "CALLBACK_FAILED";
+    readonly TOKEN_REFRESH_SUCCESS: "TOKEN_REFRESH_SUCCESS";
+    readonly TOKEN_REFRESH_FAILED: "TOKEN_REFRESH_FAILED";
+    readonly TENANT_SWITCHED: "TENANT_SWITCHED";
+    readonly LOGOUT_COMPLETED: "LOGOUT_COMPLETED";
+    readonly BOOTSTRAP_STATE_DETECTED: "BOOTSTRAP_STATE_DETECTED";
+    readonly REDIRECT_LOOP_RISK: "REDIRECT_LOOP_RISK";
+};
+type AuthEventName = (typeof AuthEventNames)[keyof typeof AuthEventNames];
+interface AuthEventPayload {
+    state?: string;
+    tenantKey?: string;
+    error?: string;
+    message?: string;
+    [key: string]: unknown;
+}
+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 InternalConfig, type Logger, OAUTH_CONSTANTS, ProtectedRoute, type ResolvedConfig, type RuntimeConfigOverrides, type SDKConfig, type RuntimeConfig as SDKRuntimeConfig, 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, getEnvConfig, getStorageAdapter, getStorageNamespace, getAccessToken as getStoredAccessToken, hasEnvFallback, isAccessTokenExpired, isCallbackUrl, logout, refreshAccessToken, resetCookieWatcher, resolveConfig, resolveTenant, sanitizeErrorMessage, setAuthRuntime, setConfig, setStorageContext, startCookieWatcher, stopCookieWatcher, subscribeAuthEvent, useAuth, useAuthContext, useAuthInit };