@naylence/runtime 0.3.5-test.910 → 0.3.5-test.913

package/dist/esm/naylence/fame/security/auth/oauth2-pkce-token-provider.js

@@ -0,0 +1,555 @@
+import { getLogger } from '../../util/logging.js';
+import { credentialToString, } from '../credential/credential-provider.js';
+const logger = getLogger('naylence.fame.security.auth.oauth2_pkce_token_provider');
+const DEFAULT_SCOPES = [];
+const DEFAULT_CLOCK_SKEW_SECONDS = 30;
+const DEFAULT_CODE_VERIFIER_LENGTH = 48; // bytes before base64url encoding
+const DEFAULT_CODE_CHALLENGE_METHOD = 'S256';
+function normalizeScopes(candidate) {
+    if (Array.isArray(candidate)) {
+        const scopes = candidate
+            .map((scope) => (typeof scope === 'string' ? scope.trim() : ''))
+            .filter((scope) => scope.length > 0);
+        return scopes.length > 0 ? scopes : undefined;
+    }
+    if (typeof candidate === 'string') {
+        const scopes = candidate
+            .split(/[,\s]+/u)
+            .map((scope) => scope.trim())
+            .filter((scope) => scope.length > 0);
+        return scopes.length > 0 ? scopes : undefined;
+    }
+    return undefined;
+}
+function coerceString(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function coerceNumber(value) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === 'string' && value.trim().length > 0) {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    return undefined;
+}
+function normalizeOptions(raw) {
+    const camel = raw;
+    const snake = raw;
+    const authorizeUrl = coerceString(camel.authorizeUrl) ?? coerceString(snake.authorize_url);
+    if (!authorizeUrl) {
+        throw new Error('OAuth2PkceTokenProvider authorizeUrl must be provided');
+    }
+    const tokenUrl = coerceString(camel.tokenUrl) ?? coerceString(snake.token_url);
+    if (!tokenUrl) {
+        throw new Error('OAuth2PkceTokenProvider tokenUrl must be provided');
+    }
+    const redirectUri = coerceString(camel.redirectUri) ?? coerceString(snake.redirect_uri);
+    if (!redirectUri) {
+        throw new Error('OAuth2PkceTokenProvider redirectUri must be provided');
+    }
+    const clientId = coerceString(camel.clientId) ?? coerceString(snake.client_id);
+    if (!clientId) {
+        throw new Error('OAuth2PkceTokenProvider clientId must be provided');
+    }
+    const usernameProvider = camel.usernameProvider ??
+        snake.username_provider;
+    const clientSecretProvider = camel.clientSecretProvider ??
+        snake.client_secret_provider;
+    const scopes = normalizeScopes(camel.scopes) ??
+        normalizeScopes(snake.scopes ?? snake.scope) ??
+        DEFAULT_SCOPES.slice();
+    const audience = coerceString(camel.audience) ??
+        coerceString(snake.audience ?? snake.aud);
+    const fetchImpl = (camel.fetchImpl ?? snake.fetch_impl);
+    const clockSkewSeconds = coerceNumber(camel.clockSkewSeconds) ??
+        coerceNumber(snake.clock_skew_seconds) ??
+        DEFAULT_CLOCK_SKEW_SECONDS;
+    const codeVerifierLength = coerceNumber(camel.codeVerifierLength) ??
+        coerceNumber(snake.code_verifier_length) ??
+        DEFAULT_CODE_VERIFIER_LENGTH;
+    const methodCandidate = coerceString(camel.codeChallengeMethod) ??
+        coerceString(snake.code_challenge_method);
+    const codeChallengeMethod = methodCandidate && methodCandidate.toUpperCase() === 'PLAIN'
+        ? 'PLAIN'
+        : DEFAULT_CODE_CHALLENGE_METHOD;
+    const loginHintParam = coerceString(camel.loginHintParam) ??
+        coerceString(snake.login_hint_param) ??
+        'login_hint';
+    return {
+        authorizeUrl,
+        tokenUrl,
+        redirectUri,
+        clientId,
+        usernameProvider,
+        clientSecretProvider,
+        scopes,
+        audience,
+        fetchImpl,
+        clockSkewSeconds,
+        codeVerifierLength,
+        codeChallengeMethod,
+        loginHintParam,
+    };
+}
+function generateRandomBytes(length) {
+    if (typeof globalThis.crypto?.getRandomValues !== 'function') {
+        throw new Error('crypto.getRandomValues is unavailable. Provide a secure random source.');
+    }
+    const buffer = new Uint8Array(length);
+    globalThis.crypto.getRandomValues(buffer);
+    return buffer;
+}
+function base64UrlEncode(buffer) {
+    const bufferCtor = globalThis.Buffer;
+    if (bufferCtor) {
+        return bufferCtor
+            .from(buffer)
+            .toString('base64')
+            .replace(/\+/g, '-')
+            .replace(/\//g, '_')
+            .replace(/=+$/u, '');
+    }
+    let binary = '';
+    for (const byte of buffer) {
+        binary += String.fromCharCode(byte);
+    }
+    if (typeof globalThis.btoa === 'function') {
+        return globalThis
+            .btoa(binary)
+            .replace(/\+/g, '-')
+            .replace(/\//g, '_')
+            .replace(/=+$/u, '');
+    }
+    throw new Error('Base64 encoding is unavailable in this environment');
+}
+async function computeS256(verifier) {
+    if (typeof globalThis.crypto?.subtle !== 'object') {
+        throw new Error('crypto.subtle.digest is unavailable. Provide an environment with Web Crypto support.');
+    }
+    const encoder = new TextEncoder();
+    const digest = await globalThis.crypto.subtle.digest('SHA-256', encoder.encode(verifier));
+    return base64UrlEncode(new Uint8Array(digest));
+}
+function ensureFinitePositive(value, label) {
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new Error(`${label} must be a positive finite number`);
+    }
+    return Math.max(1, Math.floor(value));
+}
+const STORAGE_NAMESPACE = 'naylence.oauth2_pkce.';
+const TOKEN_STORAGE_SUFFIX = '.token';
+function getStorageKey(clientId) {
+    return `${STORAGE_NAMESPACE}${clientId}`;
+}
+function getTokenStorageKey(clientId) {
+    return `${STORAGE_NAMESPACE}${clientId}${TOKEN_STORAGE_SUFFIX}`;
+}
+function isBrowserEnvironment() {
+    return (typeof window !== 'undefined' &&
+        typeof window.location !== 'undefined' &&
+        typeof window.sessionStorage !== 'undefined');
+}
+function readPendingAuthorization(clientId) {
+    if (!isBrowserEnvironment()) {
+        return null;
+    }
+    try {
+        const raw = window.sessionStorage.getItem(getStorageKey(clientId));
+        if (!raw) {
+            return null;
+        }
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object') {
+            return null;
+        }
+        return parsed;
+    }
+    catch (error) {
+        logger.debug('pkce_storage_read_failed', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return null;
+    }
+}
+function writePendingAuthorization(clientId, pending) {
+    if (!isBrowserEnvironment()) {
+        return;
+    }
+    try {
+        const key = getStorageKey(clientId);
+        if (!pending) {
+            window.sessionStorage.removeItem(key);
+            return;
+        }
+        window.sessionStorage.setItem(key, JSON.stringify(pending));
+    }
+    catch (error) {
+        logger.debug('pkce_storage_write_failed', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+function stableScopeKey(scopes) {
+    if (!scopes || scopes.length === 0) {
+        return '';
+    }
+    return [...scopes].sort().join(' ');
+}
+function readPersistedToken(clientId) {
+    if (!isBrowserEnvironment()) {
+        return null;
+    }
+    try {
+        const raw = window.sessionStorage.getItem(getTokenStorageKey(clientId));
+        if (!raw) {
+            return null;
+        }
+        const parsed = JSON.parse(raw);
+        const value = coerceString(parsed.value);
+        if (!value) {
+            return null;
+        }
+        const expiresAt = coerceNumber(parsed.expiresAt);
+        const scopes = normalizeScopes(parsed.scopes);
+        const audience = coerceString(parsed.audience);
+        const record = {
+            value,
+            scopes,
+            audience,
+        };
+        if (typeof expiresAt === 'number') {
+            record.expiresAt = expiresAt;
+        }
+        return record;
+    }
+    catch (error) {
+        logger.debug('pkce_token_storage_read_failed', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return null;
+    }
+}
+function writePersistedToken(clientId, token) {
+    if (!isBrowserEnvironment()) {
+        return;
+    }
+    const key = getTokenStorageKey(clientId);
+    try {
+        if (!token) {
+            window.sessionStorage.removeItem(key);
+            return;
+        }
+        window.sessionStorage.setItem(key, JSON.stringify(token));
+    }
+    catch (error) {
+        logger.debug('pkce_token_storage_write_failed', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+function clearOAuthParamsFromUrl(url) {
+    if (!isBrowserEnvironment()) {
+        return;
+    }
+    try {
+        const cleaned = new URL(url.toString());
+        cleaned.searchParams.delete('code');
+        cleaned.searchParams.delete('state');
+        cleaned.searchParams.delete('error');
+        cleaned.searchParams.delete('error_description');
+        cleaned.searchParams.delete('error_description'.toUpperCase());
+        cleaned.searchParams.delete('scope');
+        cleaned.searchParams.delete('scope'.toUpperCase());
+        const finalUrl = `${cleaned.pathname}${cleaned.search}${cleaned.hash}`;
+        window.history.replaceState(window.history.state, '', finalUrl);
+    }
+    catch (error) {
+        logger.debug('pkce_replace_state_failed', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+function collectRedirectOutcome(currentLocation) {
+    const url = new URL(currentLocation.href);
+    const code = url.searchParams.get('code');
+    const state = url.searchParams.get('state');
+    const error = url.searchParams.get('error');
+    const errorDescription = url.searchParams.get('error_description') ??
+        url.searchParams.get('error_description'.toUpperCase());
+    if (!code && !error) {
+        return null;
+    }
+    return {
+        code: code ?? '',
+        state: state ?? '',
+        error: error ?? undefined,
+        errorDescription: errorDescription ?? undefined,
+    };
+}
+export class OAuth2PkceRedirectInitiatedError extends Error {
+    constructor(message = 'OAuth2PkceTokenProvider initiated browser redirect') {
+        super(message);
+        this.name = 'OAuth2PkceRedirectInitiatedError';
+    }
+}
+export class OAuth2PkceTokenProvider {
+    constructor(rawOptions) {
+        this.options = normalizeOptions(rawOptions);
+    }
+    async getToken() {
+        if (!isBrowserEnvironment()) {
+            throw new Error('OAuth2PkceTokenProvider requires a browser environment with sessionStorage support');
+        }
+        if (!this.cachedToken) {
+            const persisted = readPersistedToken(this.options.clientId);
+            if (persisted) {
+                if (this.isTokenCompatible(persisted.scopes, persisted.audience)) {
+                    if (!persisted.expiresAt || this.isTokenFresh(persisted)) {
+                        logger.debug('using_persisted_oauth2_pkce_token', {
+                            authorize_url: this.options.authorizeUrl,
+                        });
+                        const cached = {
+                            value: persisted.value,
+                        };
+                        if (typeof persisted.expiresAt === 'number') {
+                            cached.expiresAt = persisted.expiresAt;
+                        }
+                        this.cachedToken = cached;
+                    }
+                    else {
+                        writePersistedToken(this.options.clientId, null);
+                    }
+                }
+                else {
+                    writePersistedToken(this.options.clientId, null);
+                }
+            }
+        }
+        if (this.cachedToken && this.isTokenFresh(this.cachedToken)) {
+            logger.debug('using_cached_oauth2_pkce_token', {
+                authorize_url: this.options.authorizeUrl,
+            });
+            return { ...this.cachedToken };
+        }
+        const tokenFromRedirect = await this.tryCompletePendingAuthorization();
+        if (tokenFromRedirect) {
+            this.cachedToken = tokenFromRedirect;
+            return { ...this.cachedToken };
+        }
+        await this.beginBrowserAuthorization();
+        throw new OAuth2PkceRedirectInitiatedError();
+    }
+    isTokenFresh(token) {
+        if (typeof token.expiresAt !== 'number') {
+            return true;
+        }
+        const skew = this.options.clockSkewSeconds ?? DEFAULT_CLOCK_SKEW_SECONDS;
+        return token.expiresAt - skew * 1000 > Date.now();
+    }
+    async beginBrowserAuthorization() {
+        const existing = readPendingAuthorization(this.options.clientId);
+        if (existing) {
+            logger.debug('pkce_redirect_in_progress', {
+                authorize_url: this.options.authorizeUrl,
+            });
+            this.navigate(existing.authorizeUrl);
+            return;
+        }
+        const verifierLength = ensureFinitePositive(this.options.codeVerifierLength ?? DEFAULT_CODE_VERIFIER_LENGTH, 'codeVerifierLength');
+        const codeVerifier = base64UrlEncode(generateRandomBytes(verifierLength));
+        const state = base64UrlEncode(generateRandomBytes(24));
+        const codeChallengeMethod = this.options.codeChallengeMethod ?? 'S256';
+        const codeChallenge = codeChallengeMethod === 'S256'
+            ? await computeS256(codeVerifier)
+            : codeVerifier;
+        const authorizeUrl = await this.buildAuthorizeUrl({
+            state,
+            codeChallenge,
+            codeChallengeMethod,
+        });
+        const pending = {
+            state,
+            codeVerifier,
+            codeChallenge,
+            codeChallengeMethod,
+            authorizeUrl,
+            createdAt: Date.now(),
+            scopes: this.options.scopes,
+            audience: this.options.audience,
+        };
+        writePersistedToken(this.options.clientId, null);
+        writePendingAuthorization(this.options.clientId, pending);
+        logger.debug('pkce_redirect_start', {
+            authorize_url: this.options.authorizeUrl,
+            redirect_uri: this.options.redirectUri,
+        });
+        this.navigate(authorizeUrl);
+    }
+    navigate(url) {
+        if (!isBrowserEnvironment()) {
+            return;
+        }
+        try {
+            window.location.assign(url);
+        }
+        catch (error) {
+            logger.error('pkce_navigation_failed', {
+                authorize_url: url,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+    }
+    async tryCompletePendingAuthorization() {
+        const pending = readPendingAuthorization(this.options.clientId);
+        if (!pending) {
+            return null;
+        }
+        const outcome = collectRedirectOutcome(window.location);
+        if (!outcome) {
+            return null;
+        }
+        clearOAuthParamsFromUrl(new URL(window.location.href));
+        writePendingAuthorization(this.options.clientId, null);
+        if (outcome.error) {
+            const suffix = outcome.errorDescription
+                ? ` - ${outcome.errorDescription}`
+                : '';
+            throw new Error(`OAuth2 authorization failed: ${outcome.error}${suffix}`);
+        }
+        if (!outcome.code) {
+            throw new Error('Authorization redirect missing code parameter');
+        }
+        if (!outcome.state || outcome.state !== pending.state) {
+            throw new Error('Authorization state mismatch');
+        }
+        const fetchImpl = this.resolveFetch();
+        const clientSecret = await this.resolveOptionalSecret(this.options.clientSecretProvider);
+        const token = await this.exchangeToken({
+            fetchImpl,
+            codeVerifier: pending.codeVerifier,
+            authorizationCode: outcome.code,
+            clientSecret,
+            scopes: pending.scopes,
+            audience: pending.audience,
+        });
+        this.persistToken(token, {
+            scopes: pending.scopes,
+            audience: pending.audience,
+        });
+        return token;
+    }
+    isTokenCompatible(scopes, audience) {
+        const expectedScopeKey = stableScopeKey(this.options.scopes);
+        const tokenScopeKey = stableScopeKey(scopes);
+        if (expectedScopeKey !== tokenScopeKey) {
+            return false;
+        }
+        const expectedAudience = this.options.audience ?? '';
+        const tokenAudience = audience ?? '';
+        return expectedAudience === tokenAudience;
+    }
+    persistToken(token, metadata) {
+        writePersistedToken(this.options.clientId, {
+            value: token.value,
+            expiresAt: token.expiresAt,
+            scopes: metadata.scopes ? [...metadata.scopes] : undefined,
+            audience: metadata.audience,
+        });
+    }
+    async buildAuthorizeUrl(params) {
+        const authorizeUrl = new URL(this.options.authorizeUrl);
+        authorizeUrl.searchParams.set('response_type', 'code');
+        authorizeUrl.searchParams.set('client_id', this.options.clientId);
+        authorizeUrl.searchParams.set('redirect_uri', this.options.redirectUri);
+        authorizeUrl.searchParams.set('state', params.state);
+        authorizeUrl.searchParams.set('code_challenge_method', params.codeChallengeMethod);
+        authorizeUrl.searchParams.set('code_challenge', params.codeChallenge);
+        if (this.options.scopes && this.options.scopes.length > 0) {
+            authorizeUrl.searchParams.set('scope', this.options.scopes.join(' '));
+        }
+        if (this.options.audience) {
+            authorizeUrl.searchParams.set('audience', this.options.audience);
+        }
+        const loginHint = await this.resolveOptionalSecret(this.options.usernameProvider);
+        if (loginHint) {
+            authorizeUrl.searchParams.set(this.options.loginHintParam ?? 'login_hint', loginHint);
+        }
+        return authorizeUrl.toString();
+    }
+    resolveFetch() {
+        if (this.options.fetchImpl) {
+            return this.options.fetchImpl;
+        }
+        if (typeof fetch === 'function') {
+            return fetch.bind(globalThis);
+        }
+        throw new Error('Global fetch implementation is not available. Provide fetchImpl in options.');
+    }
+    async resolveOptionalSecret(provider) {
+        if (!provider) {
+            return undefined;
+        }
+        const value = credentialToString(await provider.get());
+        return value ?? undefined;
+    }
+    async exchangeToken(params) {
+        const { fetchImpl, codeVerifier, authorizationCode, clientSecret, scopes, audience, } = params;
+        const form = new URLSearchParams({
+            grant_type: 'authorization_code',
+            client_id: this.options.clientId,
+            code: authorizationCode,
+            redirect_uri: this.options.redirectUri,
+            code_verifier: codeVerifier,
+        });
+        if (scopes && scopes.length > 0) {
+            form.set('scope', scopes.join(' '));
+        }
+        if (audience) {
+            form.set('audience', audience);
+        }
+        if (clientSecret) {
+            form.set('client_secret', clientSecret);
+        }
+        const response = await fetchImpl(this.options.tokenUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: form.toString(),
+        });
+        if (!response.ok) {
+            const errorBody = await response.text().catch(() => '<unavailable>');
+            throw new Error(`OAuth2 PKCE token request failed: ${response.status} ${response.statusText} - ${errorBody}`);
+        }
+        const payload = (await response.json());
+        const accessToken = payload.access_token;
+        if (typeof accessToken !== 'string' || accessToken.length === 0) {
+            throw new Error('OAuth2 PKCE token response missing access_token');
+        }
+        const expiresInCandidate = typeof payload.expires_in === 'number'
+            ? payload.expires_in
+            : typeof payload.expires === 'number'
+                ? payload.expires
+                : undefined;
+        const expiresInSeconds = expiresInCandidate && Number.isFinite(expiresInCandidate)
+            ? Math.max(1, Math.floor(expiresInCandidate))
+            : 3600;
+        const token = {
+            value: accessToken,
+            expiresAt: Date.now() + expiresInSeconds * 1000,
+        };
+        logger.debug('oauth2_pkce_token_fetched', {
+            authorize_url: this.options.authorizeUrl,
+            token_url: this.options.tokenUrl,
+            expires_in: expiresInSeconds,
+            scopes,
+            audience,
+        });
+        return token;
+    }
+}