oracledb 7.0.1 → 26.0.0

package/plugins/token/endUserSecurityProvider/index.js

@@ -0,0 +1,377 @@
+// Copyright (c) 2026, Oracle and/or its affiliates.
+
+//-----------------------------------------------------------------------------
+//
+// This software is dual-licensed to you under the Universal Permissive License
+// (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License
+// 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose
+// either license.
+//
+// If you elect to accept the software under the Apache License, Version 2.0,
+// the following applies:
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+//-----------------------------------------------------------------------------
+'use strict';
+
+/**
+ * End-user security context token provider. Each configured pool or standalone
+ * connection owns its provider; there is no process-global provider setting.
+ */
+const oracledb = require('oracledb');
+const securityContextProvider = oracledb.getSecurityContextProvider();
+
+const hasOwn = (obj, prop) => Object.prototype.hasOwnProperty.call(obj, prop);
+// These endUserSecParams fields are consumed by this provider and must not be
+// forwarded to an Azure or OCI token extension as token configuration.
+const PROVIDER_CONTROL_FIELDS = new Set([
+  'spiType', 'authFlow', 'endUserToken', 'endUserName',
+  'dataRoles', 'attributes', 'key',
+  'cacheOptions', 'contextResolution'
+]);
+const DEFAULT_METADATA_FIELDS = [
+  'endUserToken', 'endUserName', 'dataRoles', 'attributes', 'key',
+];
+const PROVIDER_MODULE_PATHS = {
+  azure: '../extensionAzure/index.js',
+  oci: '../extensionOci/index.js',
+};
+
+function throwErr(message, code) {
+  const err = new Error(message);
+  if (code) {
+    err.code = code;
+  }
+  throw err;
+}
+
+function ensureInvocationHook() {
+  if (!securityContextProvider.getInvocationHook?.()) {
+    securityContextProvider.setInvocationHook(
+      securityContextProvider.createInvocationHook()
+    );
+  }
+}
+
+function normalizeAuthFlow(value) {
+  const flow = String(value ?? 'onBehalfOf').trim().toLowerCase();
+  if (flow === 'app' || flow === 'clientcredentials' ||
+      flow === 'client_credentials' || flow === 'client-credentials') {
+    return 'app';
+  }
+  if (flow === 'obo' || flow === 'onbehalfof' ||
+      flow === 'on_behalf_of' || flow === 'on-behalf-of') {
+    return 'obo';
+  }
+  throwErr("endUserSecParams.authFlow must be 'app' or 'onBehalfOf'.");
+}
+
+function normalizeContextResolution(value) {
+  const resolution = String(value ?? 'connection').trim().toLowerCase();
+  if (resolution === 'connection' || resolution === 'operation') {
+    return resolution;
+  }
+  throwErr("endUserSecParams.contextResolution must be 'connection' or 'operation'.");
+}
+
+function normalizeProvider(params) {
+  const spiType = String(params.spiType ?? 'oci').trim().toLowerCase();
+  const modulePath = PROVIDER_MODULE_PATHS[spiType];
+  if (!modulePath) {
+    throwErr("endUserSecParams.spiType must be 'azure' or 'oci'.");
+  }
+  // Start with the supplied parameters, then remove fields interpreted by this
+  // end-user-security provider. The remaining tokenConfig is passed only to
+  // the selected Azure or OCI extension, so request metadata and provider
+  // controls cannot accidentally be treated as token-client options.
+  const tokenConfig = { ...params };
+  for (const key of PROVIDER_CONTROL_FIELDS) {
+    delete tokenConfig[key];
+  }
+  // Azure's application-token helper expects this value. It is harmless for
+  // OBO-capable configurations because both flows use the same credentials.
+  if (spiType === 'azure' && !tokenConfig.authType) {
+    tokenConfig.authType = 'azureserviceprincipal';
+  }
+  return {
+    vendor: spiType,
+    modulePath,
+    tokenConfig,
+    cacheOptions: params.cacheOptions ? { ...params.cacheOptions } : undefined
+  };
+}
+
+/**
+ * Creates a provider from the `endUserSecParams` shape. Configuration fields
+ * that describe the identity provider are static. `endUserToken`,
+ * `endUserName`, `key`, `dataRoles`, and `attributes` are defaults only: request
+ * metadata supplied by runWithContext() wins.
+ */
+function configureUnifiedContextProvider(params) {
+  ensureInvocationHook();
+  const config = normalizeConfig(params);
+  const provider = loadProviderModule(config.provider);
+  return createProviderFn(config, provider);
+}
+
+function mergeMetadata(defaults, current) {
+  if (!current || typeof current !== 'object') {
+    return defaults;
+  }
+  return { ...defaults, ...current };
+}
+
+function getEndUserToken(metadata) {
+  return metadata.endUserToken;
+}
+
+function createProviderFn(config, provider) {
+  const unifiedProvider = async function unifiedProvider() {
+    const current = securityContextProvider.getCurrentContext();
+    if (!current || typeof current !== "object") {
+      // Do not acquire an application token for normal work outside a scope.
+      return undefined;
+    }
+    if (hasOwn(current, 'authorization')) {
+      throwErr('Security context metadata.authorization is not supported; use endUserToken.');
+    }
+    const metadata = mergeMetadata(config.defaultMetadata, current);
+    const endUserToken = getEndUserToken(metadata);
+    // authFlow is fixed when the pool or standalone connection is created.
+    // Per-request metadata supplies identity only; it cannot select a token
+    // exchange for which the configured provider may lack credentials.
+    if (config.authFlow === "obo") {
+      if (config.provider.vendor !== 'azure') {
+        throwErr('On-behalf-of security contexts are supported only with spiType "azure".');
+      }
+      if (!endUserToken) {
+        throwErr("authFlow=obo requires an end-user token.");
+      }
+
+      const tokenResult = await acquireOboToken(config, provider, endUserToken);
+      return getOrCreateScopedSecurityContext(unifiedProvider, config,
+        tokenResult, () => createSecurityContext(finalizeOboMode(metadata,
+          tokenResult.accessToken)));
+    }
+
+    const tokenResult = await acquireAppToken(config, provider);
+    const databaseAccessToken = tokenResult.accessToken;
+    // No end-user identity means the database resolves the application
+    // identity directly from the client-credential database access token.
+    if (!endUserToken && !metadata.endUserName) {
+      // A key identifies a named database-managed end user. It is not valid
+      // for direct application logon, but roles and attributes are valid
+      // authorization metadata for either identity form.
+      if (metadata.key) {
+        throwErr("authFlow 'app' requires endUserName when key is supplied.");
+      }
+      return getOrCreateScopedSecurityContext(unifiedProvider, config,
+        tokenResult, () => createSecurityContext(
+          buildContext({
+            databaseAccessToken,
+            dataRoles: metadata.dataRoles,
+            attributes: metadata.attributes
+          })));
+    }
+    // App mode uses the application token to authorize database access and
+    // carries a supplied end-user token directly in the EUSC. This is not an
+    // OBO exchange; Azure and OCI both support this explicit identity form.
+    if (endUserToken) {
+      if (metadata.endUserName || metadata.key) {
+        throwErr('App mode cannot combine endUserToken with endUserName or key.');
+      }
+      return getOrCreateScopedSecurityContext(unifiedProvider, config,
+        tokenResult, () => createSecurityContext(finalizeAppTokenMode(metadata,
+          databaseAccessToken)));
+    }
+    if (!metadata.endUserName) {
+      throwErr("authFlow 'app' requires endUserName when endUserToken is supplied.");
+    }
+    return getOrCreateScopedSecurityContext(unifiedProvider, config,
+      tokenResult, () => createSecurityContext(
+        finalizeAppMode(metadata, databaseAccessToken)));
+  };
+  // The driver reads this private property to choose the provider lifecycle.
+  unifiedProvider._contextResolution = config.contextResolution;
+  return unifiedProvider;
+}
+
+function createSecurityContext(context) {
+  return new oracledb.EndUserSecurityContext(context);
+}
+
+// Operation resolution calls the provider for every database operation so the
+// token extension remains authoritative for expiry and refresh. When it
+// confirms the same database token came from its cache, reuse the already
+// encoded EUSC for this runWithContext() scope. The scope cache holds no
+// plaintext token and is released when the async scope completes.
+function getOrCreateScopedSecurityContext(provider, config, tokenResult,
+  createContext) {
+  if (config.contextResolution !== 'operation') {
+    return createContext();
+  }
+  const cached = securityContextProvider._getScopedValue(provider);
+  if (cached && tokenResult.isNewToken === false) {
+    return cached;
+  }
+  const securityContext = createContext();
+  securityContextProvider._setScopedValue(provider, securityContext);
+  return securityContext;
+}
+
+function finalizeOboMode(metadata, databaseAccessToken) {
+  const attributeResolution = resolveAttributesForRequest(metadata);
+  const context = {
+    databaseAccessToken,
+    dataRoles: metadata.dataRoles,
+    attributes: attributeResolution.payload
+  };
+  context.endUserToken = getEndUserToken(metadata);
+  return buildContext(context);
+}
+
+function finalizeAppMode(metadata, databaseAccessToken) {
+  const context = buildContext({
+    databaseAccessToken,
+    endUserName: metadata.endUserName,
+    dataRoles: metadata.dataRoles,
+    key: metadata.key,
+    attributes: metadata.attributes
+  });
+  return context;
+}
+
+function finalizeAppTokenMode(metadata, databaseAccessToken) {
+  return buildContext({
+    databaseAccessToken,
+    endUserToken: metadata.endUserToken,
+    dataRoles: metadata.dataRoles,
+    attributes: metadata.attributes
+  });
+}
+
+async function acquireAppToken(config, provider) {
+  const result = await provider.getTokenResult(config.provider.tokenConfig);
+  return {
+    accessToken: getAccessToken(result,
+      'Token provider failed to return an application access token.'),
+    isNewToken: result?.isNewToken !== false,
+  };
+}
+
+async function acquireOboToken(config, provider, endUserToken) {
+  const result = await provider.getOnBehalfOfToken({
+    endUserToken,
+    oboConfig: config.provider.tokenConfig,
+    cacheOptions: config.provider.cacheOptions
+  });
+  const accessToken = getAccessToken(result,
+    'Token provider failed to return an access token for on-behalf-of exchange.');
+  return {
+    accessToken,
+    // Extensions set false only when returning a valid cached database token.
+    // Unknown/custom provider results are conservative and force a new EUSC.
+    isNewToken: result?.isNewToken !== false,
+  };
+}
+
+function getAccessToken(result, errorMessage) {
+  const accessToken = typeof result === 'string'
+    ? result
+    : (result?.accessToken ?? result?.token);
+  if (typeof accessToken !== 'string' || !accessToken.trim()) {
+    throwErr(errorMessage);
+  }
+  return accessToken;
+}
+
+function loadProviderModule(descriptor) {
+  return require(descriptor.modulePath);
+}
+
+function buildContext(base) {
+  const context = { databaseAccessToken: base.databaseAccessToken };
+  for (const key of ['endUserToken', 'endUserName', 'dataRoles', 'key', 'attributes']) {
+    if (base[key] !== undefined) {
+      context[key] = base[key];
+    }
+  }
+  return context;
+}
+
+function normalizeConfig(params) {
+  if (!params || typeof params !== 'object' || Array.isArray(params)) {
+    throw new TypeError('endUserSecParams must be an object.');
+  }
+  const defaultMetadata = {};
+  for (const key of DEFAULT_METADATA_FIELDS) {
+    if (hasOwn(params, key)) {
+      defaultMetadata[key] = params[key];
+    }
+  }
+  const authFlow = normalizeAuthFlow(params.authFlow);
+  const provider = normalizeProvider(params);
+  if (authFlow === 'obo' && provider.vendor !== 'azure') {
+    throwErr('On-behalf-of security contexts are supported only with spiType "azure".');
+  }
+  return {
+    authFlow,
+    contextResolution: normalizeContextResolution(params.contextResolution),
+    defaultMetadata: snapshotDefaultMetadata(defaultMetadata),
+    provider
+  };
+}
+
+// Provider defaults are static after pool/connection creation. Snapshot the
+// mutable fields so changes to the caller's configuration object cannot alter
+// a scope after the provider has been configured.
+function snapshotDefaultMetadata(metadata) {
+  const snapshot = { ...metadata };
+  if (Array.isArray(metadata.dataRoles)) {
+    snapshot.dataRoles = [...metadata.dataRoles];
+  }
+  if (metadata.attributes && typeof metadata.attributes === 'object') {
+    snapshot.attributes = JSON.parse(JSON.stringify(metadata.attributes));
+  }
+  return snapshot;
+}
+
+function resolveAttributesForRequest(metadata) {
+  if (!hasOwn(metadata, 'attributes')) {
+    return { payload: undefined };
+  }
+  try {
+    JSON.stringify(metadata.attributes);
+  } catch (err) {
+    const error = new Error('security context attributes must be JSON-serializable.');
+    error.cause = err;
+    throw error;
+  }
+  return { payload: metadata.attributes };
+}
+
+/**
+ * Process configuration hook. `endUserSecParams` is copied to the pool or
+ * standalone connection being created. Dynamic request metadata is supplied
+ * later with runWithContext().
+ */
+function hookFn(options) {
+  if (!options.endUserSecParams) {
+    return;
+  }
+  options._securityContextProvider =
+    configureUnifiedContextProvider(options.endUserSecParams);
+}
+
+oracledb.registerProcessConfigurationHook(hookFn);

package/plugins/token/extensionAzure/index.js

@@ -26,9 +26,27 @@
 'use strict';
 const oracledb = require('oracledb');
 const msal = require('@azure/msal-node');
+const { TokenCache, hashValue } = require('../cache.js');
 
+const OBO_DEFAULT_CLOCK_SKEW_MS = 60 * 1000;
+const TOKEN_CACHE_MAX_ENTRIES = 100;
+// Process-wide, bounded LRU cache of completed OBO exchanges. Connections
+// safely share entries only when their cache key has the same caller-token
+// hash and every Azure credential/request input that can change the result.
+// Values are obfuscated at rest.
+const oboTokenCache = new TokenCache(TOKEN_CACHE_MAX_ENTRIES);
+// Process-wide, bounded cache of service-principal tokens. Its key includes
+// every credential and request input that can change the resulting token, so
+// pools can share only compatible entries. Values are obfuscated at rest.
+const appTokenCache = new TokenCache(TOKEN_CACHE_MAX_ENTRIES);
 
-async function getToken(params) {
+
+// Internal Deep Security API. The driver's ordinary token-authentication hook
+// below returns this result's access-token string.
+async function getTokenResult(params) {
+  if (typeof params?.authType !== 'string') {
+    throwErr('Azure authentication type is required.');
+  }
   switch (params.authType.toLowerCase()) {
     case 'azureserviceprincipal':
       return await servicePrincipalCredentials(params);
@@ -46,9 +64,7 @@ function throwErr(message) {
 
 //---------------------------------------------------------------------------
 // Returns the access token for authentication as a service principal. This
-// authentication method requires a client ID along with either a secret or
-// certificate. These values may be provided as config parameters read by
-// the Azure SDK.
+// authentication method requires a client ID and client secret.
 // ---------------------------------------------------------------------------
 async function servicePrincipalCredentials(params) {
   const clientId = params.clientId ??
@@ -57,31 +73,24 @@ async function servicePrincipalCredentials(params) {
     throwErr("Token based authentication config parameter authority is missing for azureServicePrincipal in extensionAzure plugins.");
   const clientSecret = params.clientSecret ??
     throwErr("Token based authentication config parameter clientSecret is missing for azureServicePrincipal in extensionAzure plugins.");
-  const msalConfig = {
-    auth: {
-      clientId: clientId,
-      authority: authority,
-      clientSecret: clientSecret,
-    },
-    system: {
-      // Use it while generating azure tokens behind proxy
-      // Otherwise can remove this option
-      networkClient: params.proxy,
-    },
-  };
-
-  if (!msalConfig.system.networkClient) {
-    delete msalConfig.system.networkClient;
-  }
-
   const scopes = params.scopes ??
     throwErr("Token based authentication config parameter scopes is missing for azureServicePrincipal in extensionAzure plugins.");
-  const tokenRequest = {
-    scopes: [scopes],
-  };
-  const cca = new msal.ConfidentialClientApplication(msalConfig);
-  const authResponse = await cca.acquireTokenByClientCredential(tokenRequest);
-  return authResponse.accessToken;
+  const normalizedScopes = normalizeScopes(scopes);
+  const config = { ...params, clientId, authority, clientSecret };
+  const cacheKey = computeAppCacheKey(config, normalizedScopes);
+  const result = await appTokenCache.get(cacheKey, async () => {
+    const authResponse = await createClient(config).acquireTokenByClientCredential({
+      scopes: normalizedScopes,
+    });
+    if (!authResponse?.accessToken) {
+      throwErr('Failed to acquire application access token from Azure.');
+    }
+    return {
+      value: authResponse.accessToken,
+      validUntil: calculateExpiry(authResponse, OBO_DEFAULT_CLOCK_SKEW_MS),
+    };
+  });
+  return { accessToken: result.value, isNewToken: !result.isCacheHit };
 }
 
 // ---------------------------------------------------------------------------
@@ -92,9 +101,132 @@ async function servicePrincipalCredentials(params) {
 function hookFn(options) {
   if (options.tokenAuthConfigAzure) {
     options.accessToken = async function callbackFn(refresh, config) {
-      return await getToken(config);
+      return (await getTokenResult(config)).accessToken;
     };
     options.accessTokenConfig = options.tokenAuthConfigAzure;
   }
 }
 oracledb.registerProcessConfigurationHook(hookFn);
+
+//---------------------------------------------------------------------------
+// normalizeScopes()
+//---------------------------------------------------------------------------
+function normalizeScopes(scopes) {
+  const normalized = Array.isArray(scopes)
+    ? scopes
+    : (typeof scopes === 'string' ? [scopes] : null);
+  if (!normalized || normalized.some((scope) =>
+    typeof scope !== 'string' || !scope.trim())) {
+    throwErr('Azure scopes must be a string or an array of non-empty strings.');
+  }
+  return normalized.map((scope) => scope.trim()).sort();
+}
+
+//---------------------------------------------------------------------------
+// buildNetworkClient()
+//---------------------------------------------------------------------------
+function buildNetworkClient(proxyConfig) {
+  if (!proxyConfig) {
+    return null;
+  }
+  if (typeof proxyConfig.sendGetRequestAsync === 'function' &&
+      typeof proxyConfig.sendPostRequestAsync === 'function') {
+    return proxyConfig;
+  }
+  throwErr('Azure proxy configuration must implement sendGetRequestAsync() and sendPostRequestAsync().');
+}
+
+//---------------------------------------------------------------------------
+// computeOboCacheKey()
+//---------------------------------------------------------------------------
+function computeOboCacheKey(config, scopes, endUserToken) {
+  // Do not put the assertion or client secret itself in a process-wide Map.
+  // The secret hash separates entries if a client secret is rotated while the
+  // process is running.
+  return JSON.stringify([
+    config.authType?.toLowerCase(), config.clientId,
+    hashValue(config.clientSecret), config.authority, scopes,
+    hashValue(endUserToken),
+  ]);
+}
+
+function computeAppCacheKey(config, scopes) {
+  // Hash the secret rather than retaining it in the process-wide key. A
+  // changed secret creates a new entry, leaving the old one bounded and
+  // eligible for LRU eviction.
+  return JSON.stringify([
+    config.authType?.toLowerCase(), config.clientId,
+    hashValue(config.clientSecret), config.authority, scopes,
+  ]);
+}
+
+function createClient(config) {
+  const networkClient = buildNetworkClient(config.proxy);
+  const msalConfig = {
+    auth: {
+      clientId: config.clientId ?? throwErr("OBO configuration requires clientId."),
+      authority: config.authority ?? throwErr("OBO configuration requires authority."),
+      clientSecret: config.clientSecret ?? throwErr("OBO configuration requires clientSecret."),
+    }
+  };
+  if (networkClient) {
+    msalConfig.system = { networkClient };
+  }
+
+  return new msal.ConfidentialClientApplication(msalConfig);
+}
+
+//---------------------------------------------------------------------------
+// calculateExpiry()
+//---------------------------------------------------------------------------
+function calculateExpiry(result, clockSkewMs) {
+  if (result?.expiresOn instanceof Date) {
+    return result.expiresOn.getTime() - clockSkewMs;
+  }
+  throwErr('Azure token response did not include an expiration time.');
+}
+
+//---------------------------------------------------------------------------
+// getOnBehalfOfToken()
+//---------------------------------------------------------------------------
+async function getOnBehalfOfToken({ endUserToken, oboConfig, cacheOptions }) {
+  if (!endUserToken) {
+    throwErr('An end user access token must be supplied for OBO exchange.');
+  }
+  if (!oboConfig) {
+    throwErr('OBO configuration is required.');
+  }
+
+  const scopes = normalizeScopes(oboConfig.scopes);
+  const cacheEnabled = cacheOptions?.enabled !== false;
+  const clockSkewMs = cacheOptions?.clockSkewMs ?? OBO_DEFAULT_CLOCK_SKEW_MS;
+  // This process-wide bounded cache is authoritative. Do not use MSAL's
+  // per-client cache because clients are intentionally short-lived so they do
+  // not retain credentials in a long-lived object graph.
+
+  const cacheKey = computeOboCacheKey(oboConfig, scopes, endUserToken);
+  const result = await oboTokenCache.get(cacheKey, async () => {
+    const authResponse = await createClient(oboConfig).acquireTokenOnBehalfOf({
+      oboAssertion: endUserToken,
+      scopes,
+      skipCache: true
+    });
+    if (!authResponse?.accessToken) {
+      throwErr('Failed to acquire on-behalf-of access token from Azure.');
+    }
+    return {
+      value: authResponse.accessToken,
+      validUntil: calculateExpiry(authResponse, clockSkewMs),
+    };
+  }, { enabled: cacheEnabled });
+  return {
+    accessToken: result.value,
+    expiresOn: new Date(result.validUntil + clockSkewMs),
+    isNewToken: !result.isCacheHit,
+  };
+}
+
+module.exports = {
+  getTokenResult,
+  getOnBehalfOfToken
+};