import { createHash } from "node:crypto"; import { loadRequiredWebConfig, type WebConfig } from "@hivegrid/config"; import { KWP_OIDC_ISSUER, KWP_REQUIRED_OAUTH_SCOPES, isValidKwpContextCode, isValidKwpReturnedOAuthScopes, type KwpCredentials as IntegrationKwpCredentials, } from "@hivegrid/integrations"; import { Issuer, type CallbackParamsType, type Client, type TokenSet } from "openid-client"; import { KWP_OAUTH_CALLBACK_PATH } from "~/utils/integrations/integrationsRoutePaths"; const KWP_AUTHORIZATION_ENDPOINT = `${KWP_OIDC_ISSUER}/protocol/openid-connect/auth`; const KWP_TOKEN_ENDPOINT = `${KWP_OIDC_ISSUER}/protocol/openid-connect/token`; const KWP_JWKS_URI = `${KWP_OIDC_ISSUER}/protocol/openid-connect/certs`; const KWP_SCOPE_ORDER = KWP_REQUIRED_OAUTH_SCOPES; const KWP_SCOPE_SET = new Set(KWP_SCOPE_ORDER); const KWP_DOMAIN_SCOPES = KWP_SCOPE_ORDER.filter((scope) => scope.endsWith("-extern")); const HIVEGRID_TENANT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,255}$/u; const KWP_ACCESS_TOKEN_TTL_SECONDS = 5 * 60; type KwpOidcClientErrorCode = | "missing-config" | "invalid-issuer" | "invalid-scope" | "invalid-input" | "discovery-failed" | "issuer-mismatch" | "discovery-contract-mismatch" | "client-init-failed" | "authorization-failed" | "callback-failed" | "invalid-token-response"; export type KwpOidcDiagnosticCode = | "provider_access_denied" | "provider_invalid_client" | "provider_invalid_grant" | "provider_invalid_scope" | "provider_server_error" | "provider_temporarily_unavailable" | "provider_unauthorized_client" | "oidc_rp_error" | "token_exchange_failed" | "missing_access_token" | "missing_refresh_token" | "invalid_expiry" | "scope_mismatch"; export class KwpOidcClientError extends Error { readonly code: KwpOidcClientErrorCode; readonly diagnosticCode?: KwpOidcDiagnosticCode; constructor(code: KwpOidcClientErrorCode, message: string, options?: { cause?: unknown; diagnosticCode?: KwpOidcDiagnosticCode }) { super(message, options); this.name = "KwpOidcClientError"; this.code = code; this.diagnosticCode = options?.diagnosticCode; } } export type KwpOidcRuntimeConfig = { readonly issuer: typeof KWP_OIDC_ISSUER; readonly clientId: string; readonly clientSecret: string; readonly customerCode: string; readonly hiveGridTenantId: string; readonly scopes: string; readonly redirectUri: string; }; export type KwpAuthorizationPayload = { readonly state: string; readonly nonce: string; readonly codeChallenge: string; readonly customerCode: string; }; export type KwpAuthorizationCodeChecks = { readonly state: string; readonly nonce: string; readonly codeVerifier: string; readonly customerCode: string; }; export type KwpAuthorizationCallbackParameters = { readonly code: string; readonly state: string; readonly iss?: string; }; export type KwpCredentials = IntegrationKwpCredentials; export type KwpAuthorizationCodeExchangeResult = { readonly credentials: KwpCredentials; readonly tokenExpiresAt: Date; }; type KwpWebConfig = Pick; type DiscoveredIssuer = Awaited>; type DiscoverIssuer = (issuer: string) => Promise; const defaultDiscoverIssuer: DiscoverIssuer = (issuer) => Issuer.discover(issuer); let discoverIssuer: DiscoverIssuer = defaultDiscoverIssuer; let cachedClient: Promise | null = null; let cachedClientFingerprint: string | null = null; /** Read and strictly validate the process-wide KWP OAuth provider contract. */ export function readKwpOidcRuntimeConfig(config: KwpWebConfig = loadRequiredWebConfig()): KwpOidcRuntimeConfig { const clientId = present(config.kwp?.clientId); const clientSecret = present(config.kwp?.clientSecret); const rawScopes = present(config.kwp?.scopes); const customerCode = present(config.kwp?.customerCode); const oidcIssuer = present(config.kwp?.oidcIssuer); const hiveGridTenantId = present(config.kwp?.hiveGridTenantId); const missing = [ ["KWP_OAUTH_CLIENT_ID", clientId], ["KWP_OAUTH_CLIENT_SECRET", clientSecret], ["KWP_OAUTH_SCOPES", rawScopes], ["KWP_CUSTOMER_CODE", customerCode], ["KWP_OIDC_ISSUER", oidcIssuer], ["KWP_HIVEGRID_TENANT_ID", hiveGridTenantId], ] .filter((entry): entry is [string, undefined] => entry[1] === undefined) .map(([name]) => name); if (!clientId || !clientSecret || !rawScopes || !customerCode || !oidcIssuer || !hiveGridTenantId) { throw new KwpOidcClientError("missing-config", `KWP OAuth configuration is incomplete: missing ${missing.join(", ")}.`); } if (oidcIssuer !== KWP_OIDC_ISSUER) { throw new KwpOidcClientError("invalid-issuer", "KWP_OIDC_ISSUER must match the approved KWP federated realm exactly."); } if (!HIVEGRID_TENANT_ID_PATTERN.test(hiveGridTenantId) || !isValidKwpContextCode(customerCode)) { throw new KwpOidcClientError("invalid-input", "The configured tenant or KWP context identifier is invalid."); } return { issuer: KWP_OIDC_ISSUER, clientId, clientSecret, customerCode, hiveGridTenantId, scopes: normalizeConfiguredScopes(rawScopes), redirectUri: `${config.routing.protocol}://${config.routing.webAppHost}${KWP_OAUTH_CALLBACK_PATH}`, }; } /** Discover and cache the verified KWP OIDC client for the active configuration. */ export async function getKwpOidcClient(runtimeConfig: KwpOidcRuntimeConfig = readKwpOidcRuntimeConfig()): Promise { const fingerprint = runtimeFingerprint(runtimeConfig); if (cachedClient && cachedClientFingerprint === fingerprint) { return cachedClient; } const pendingClient = initializeClient(runtimeConfig); cachedClient = pendingClient; cachedClientFingerprint = fingerprint; try { return await pendingClient; } catch (error) { if (cachedClient === pendingClient) { cachedClient = null; cachedClientFingerprint = null; } throw error; } } /** Build the Authorization Code + PKCE request for KWP Keycloak. */ export async function buildKwpAuthorizationUrl(payload: KwpAuthorizationPayload): Promise { const runtimeConfig = readKwpOidcRuntimeConfig(); requireInput("state", payload.state); requireInput("nonce", payload.nonce); requireInput("codeChallenge", payload.codeChallenge); requireInput("customerCode", payload.customerCode); if (payload.customerCode !== runtimeConfig.customerCode) { throw new KwpOidcClientError("invalid-input", "The KWP authorization customer code does not match the configured connection."); } const client = await getKwpOidcClient(runtimeConfig); try { return client.authorizationUrl({ response_type: "code", redirect_uri: runtimeConfig.redirectUri, scope: runtimeConfig.scopes, state: payload.state, nonce: payload.nonce, code_challenge: payload.codeChallenge, code_challenge_method: "S256", tenant: runtimeConfig.customerCode, }); } catch (cause) { throw new KwpOidcClientError("authorization-failed", "The KWP authorization request could not be created.", { cause }); } } /** Exchange and verify the returned KWP authorization response. */ export async function exchangeKwpAuthorizationCode( callbackInput: KwpAuthorizationCallbackParameters, checks: KwpAuthorizationCodeChecks ): Promise { const runtimeConfig = readKwpOidcRuntimeConfig(); requireInput("code", callbackInput.code); requireInput("callback state", callbackInput.state); requireInput("state", checks.state); requireInput("nonce", checks.nonce); requireInput("codeVerifier", checks.codeVerifier); requireInput("customerCode", checks.customerCode); if (checks.customerCode !== runtimeConfig.customerCode) { throw new KwpOidcClientError("invalid-input", "The KWP callback customer code does not match the configured connection."); } const client = await getKwpOidcClient(runtimeConfig); let tokenSet: TokenSet; try { const callbackParams: CallbackParamsType = { code: callbackInput.code, state: callbackInput.state, ...(callbackInput.iss ? { iss: callbackInput.iss } : {}), }; tokenSet = await client.callback(runtimeConfig.redirectUri, callbackParams, { state: checks.state, nonce: checks.nonce, code_verifier: checks.codeVerifier, }); } catch (cause) { throw new KwpOidcClientError("callback-failed", "The KWP authorization response could not be verified or exchanged.", { cause, diagnosticCode: callbackFailureDiagnosticCode(cause), }); } const accessToken = requiredToken(tokenSet.access_token, "access token", "missing_access_token"); const refreshToken = requiredToken(tokenSet.refresh_token, "refresh token", "missing_refresh_token"); const expiresAt = tokenExpiry(tokenSet); if (tokenSet.scope !== undefined && !isValidKwpReturnedOAuthScopes(tokenSet.scope)) { throw new KwpOidcClientError("invalid-token-response", "The returned KWP OAuth scope set is invalid.", { diagnosticCode: "scope_mismatch", }); } return { credentials: { accessToken, refreshToken, expiresAt: expiresAt.toISOString(), issuer: runtimeConfig.issuer, clientId: runtimeConfig.clientId, clientSecret: runtimeConfig.clientSecret, customerCode: runtimeConfig.customerCode, // Persist the canonical HiveGrid request/policy set, not Keycloak's // permitted reduced scope echo from this individual token response. scopes: [...KWP_REQUIRED_OAUTH_SCOPES], }, tokenExpiresAt: expiresAt, }; } async function initializeClient(runtimeConfig: KwpOidcRuntimeConfig): Promise { let discoveredIssuer: DiscoveredIssuer; try { discoveredIssuer = await discoverIssuer(runtimeConfig.issuer); } catch (cause) { throw new KwpOidcClientError("discovery-failed", "KWP OIDC discovery failed.", { cause }); } if (discoveredIssuer.metadata.issuer !== runtimeConfig.issuer) { throw new KwpOidcClientError("issuer-mismatch", "KWP OIDC discovery returned an unapproved issuer."); } validateDiscoveryContract(discoveredIssuer.metadata); try { return new discoveredIssuer.Client({ client_id: runtimeConfig.clientId, client_secret: runtimeConfig.clientSecret, redirect_uris: [runtimeConfig.redirectUri], response_types: ["code"], token_endpoint_auth_method: "client_secret_post", }); } catch (cause) { throw new KwpOidcClientError("client-init-failed", "The KWP OIDC client could not be initialized.", { cause }); } } function validateDiscoveryContract(metadata: DiscoveredIssuer["metadata"]): void { const endpointsMatch = metadata.authorization_endpoint === KWP_AUTHORIZATION_ENDPOINT && metadata.token_endpoint === KWP_TOKEN_ENDPOINT && metadata.jwks_uri === KWP_JWKS_URI; const capabilitiesMatch = metadataIncludes(metadata, "code_challenge_methods_supported", ["S256"]) && metadataIncludes(metadata, "grant_types_supported", ["authorization_code", "refresh_token"]) && metadataIncludes(metadata, "token_endpoint_auth_methods_supported", ["client_secret_post"]); if (!endpointsMatch || !capabilitiesMatch) { throw new KwpOidcClientError("discovery-contract-mismatch", "KWP OIDC discovery does not match the approved endpoint and capability contract."); } } function metadataIncludes(metadata: DiscoveredIssuer["metadata"], field: string, requiredValues: readonly string[]): boolean { const advertisedValues = metadata[field]; return Array.isArray(advertisedValues) && requiredValues.every((value) => advertisedValues.includes(value)); } function runtimeFingerprint(runtimeConfig: KwpOidcRuntimeConfig): string { const secretHash = createHash("sha256").update(runtimeConfig.clientSecret).digest("base64url"); return [ runtimeConfig.issuer, runtimeConfig.clientId, runtimeConfig.redirectUri, runtimeConfig.customerCode, runtimeConfig.hiveGridTenantId, runtimeConfig.scopes, secretHash, ].join("|"); } function normalizeConfiguredScopes(rawScopes: string): string { const scopes = rawScopes.split(/\s+/u).filter(Boolean); const scopeSet = new Set(scopes); const onlyApprovedScopes = [...scopeSet].every((scope) => KWP_SCOPE_SET.has(scope)); const includesEveryDomainScope = KWP_DOMAIN_SCOPES.every((scope) => scopeSet.has(scope)); const valid = onlyApprovedScopes && includesEveryDomainScope; if (!valid) { throw new KwpOidcClientError( "invalid-scope", "The configured KWP OAuth scopes must include all approved domain scopes and no unapproved scope.", ); } return KWP_SCOPE_ORDER.join(" "); } function requiredToken(value: string | undefined, label: string, diagnosticCode: KwpOidcDiagnosticCode): string { const normalized = value?.trim(); if (!normalized) { throw new KwpOidcClientError("invalid-token-response", `The KWP token response did not contain a ${label}.`, { diagnosticCode, }); } return normalized; } function tokenExpiry(tokenSet: TokenSet): Date { const nowSeconds = Math.floor(Date.now() / 1_000); const expiresIn = tokenSet.expires_in; if ( expiresIn !== undefined && (typeof expiresIn !== "number" || !Number.isSafeInteger(expiresIn) || expiresIn <= 0 || expiresIn > KWP_ACCESS_TOKEN_TTL_SECONDS) ) { throw invalidExpiryError(); } const expiresAtSeconds = tokenSet.expires_at ?? (expiresIn !== undefined ? nowSeconds + expiresIn : undefined); const remainingSeconds = typeof expiresAtSeconds === "number" ? expiresAtSeconds - nowSeconds : Number.NaN; if ( typeof expiresAtSeconds !== "number" || !Number.isSafeInteger(expiresAtSeconds) || !Number.isSafeInteger(remainingSeconds) || remainingSeconds <= 0 || remainingSeconds > KWP_ACCESS_TOKEN_TTL_SECONDS ) { throw invalidExpiryError(); } const expiresAt = new Date(expiresAtSeconds * 1_000); if (Number.isNaN(expiresAt.getTime())) { throw invalidExpiryError(); } return expiresAt; } function invalidExpiryError(): KwpOidcClientError { return new KwpOidcClientError("invalid-token-response", "The KWP token response did not contain a valid expiry.", { diagnosticCode: "invalid_expiry", }); } const PROVIDER_ERROR_DIAGNOSTICS: Readonly> = Object.freeze({ access_denied: "provider_access_denied", invalid_client: "provider_invalid_client", invalid_grant: "provider_invalid_grant", invalid_scope: "provider_invalid_scope", server_error: "provider_server_error", temporarily_unavailable: "provider_temporarily_unavailable", unauthorized_client: "provider_unauthorized_client", }); function callbackFailureDiagnosticCode(cause: unknown): KwpOidcDiagnosticCode { if (cause && typeof cause === "object") { const providerError = "error" in cause ? cause.error : undefined; if (typeof providerError === "string" && Object.hasOwn(PROVIDER_ERROR_DIAGNOSTICS, providerError)) { return PROVIDER_ERROR_DIAGNOSTICS[providerError]; } } if (cause instanceof Error && cause.name === "RPError") { return "oidc_rp_error"; } return "token_exchange_failed"; } function requireInput(name: string, value: string): void { if (!present(value)) { throw new KwpOidcClientError("invalid-input", `KWP OAuth ${name} is required.`); } } function present(value: string | undefined): string | undefined { const trimmed = value?.trim(); return trimmed ? trimmed : undefined; } /** Test-only seam for deterministic discovery and client construction. */ export function __setKwpOidcDiscoveryForTests(discovery: DiscoverIssuer): void { discoverIssuer = discovery; cachedClient = null; cachedClientFingerprint = null; } /** Test-only: restore real discovery and clear the process-wide client cache. */ export function __resetKwpOidcClientForTests(): void { discoverIssuer = defaultDiscoverIssuer; cachedClient = null; cachedClientFingerprint = null; }