oracledb 7.0.0 → 26.0.0

package/plugins/configProviders/gcpstorage/index.js

@@ -0,0 +1,121 @@
+// 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";
+
+const util = require("node:util");
+const { base } = require("../base.js");
+const oracledb = require("oracledb");
+
+let Storage;
+
+class GCPStorageProvider extends base {
+  constructor(provider_arg, urlExtendedPart) {
+    super(urlExtendedPart);
+    this.parseProviderArg(provider_arg);
+  }
+
+  init() {
+    ({ Storage } = require("@google-cloud/storage"));
+  }
+
+  parseProviderArg(providerArg) {
+    for (const entry of providerArg.split(";")) {
+      const [key, ...valueParts] = entry.split("=");
+      const value = valueParts.join("=");
+
+      if (!key || !value) {
+        throw new Error(
+          "GCP Storage Config Provider argument must use bucket=<bucket>;object=<object>;project=<project> is optional."
+        );
+      }
+
+      this._addParam(key.trim(), decodeURIComponent(value.trim()));
+    }
+
+    for (const key of ["bucket", "object"]) {
+      if (!this.paramMap.get(key)) {
+        throw new Error(
+          `GCP Storage Config Provider missing required ${key} value.`
+        );
+      }
+    }
+  }
+
+  async returnConfig() {
+    const bucket = this.paramMap.get("bucket");
+    const object = this.paramMap.get("object");
+
+    const storageOptions = {};
+    const projectId = this.paramMap.get("project");
+    if (projectId) {
+      storageOptions.projectId = projectId;
+    }
+
+    // The Storage client manages the lifecycle of its underlying connections,
+    // no explicit close is required after downloading the configuration.
+    const storage = new Storage(storageOptions);
+
+    try {
+      const [contents] = await storage
+        .bucket(bucket)
+        .file(object)
+        .download();
+      return JSON.parse(contents.toString("utf-8"));
+    } catch (e) {
+      const errmsg = util.format(
+        "Failed to retrieve or parse config from GCP Storage: %s\n%s",
+        e.message,
+        e.stack
+      );
+      throw new Error(errmsg);
+    }
+  }
+}
+
+module.exports = GCPStorageProvider;
+
+async function hookFn(args) {
+  const configProvider = new GCPStorageProvider(
+    args.provider_arg,
+    args.urlExtendedPart
+  );
+
+  try {
+    configProvider.init();
+  } catch (err) {
+    const errmsg = util.format(
+      "GCP Storage Config Provider failed to load required modules: %s\n%s",
+      err.message,
+      err.stack
+    );
+    throw new Error(errmsg);
+  }
+
+  const cfg = await configProvider.returnConfig();
+  return [cfg, null];
+}
+
+oracledb.registerConfigurationProviderHook("gcpstorage", hookFn);

package/plugins/configProviders/ociobject/index.js

@@ -87,7 +87,7 @@ class OCIProvider extends base {
       if (auth == 'OCI_INSTANCE_PRINCIPAL') {
         provider = await oci.common.InstancePrincipalsAuthenticationDetailsProviderBuilder().build();
       } else if (auth == 'OCI_RESOURCE_PRINCIPAL') {
-        provider = await new oci.common.ResourcePrincipalAuthenticationDetailsProvider.builder();
+        provider = oci.common.ResourcePrincipalAuthenticationDetailsProvider.builder();
       } else {
         const errmsg = util.format('OCI authentication failed: The authentication parameter value %s may be incorrect', auth);
         throw new Error(errmsg);

package/plugins/token/cache.js

@@ -0,0 +1,154 @@
+// 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.
+//
+// Shared process-wide token-cache support for built-in token extensions.
+//-----------------------------------------------------------------------------
+'use strict';
+
+const crypto = require('crypto');
+const { ObfuscatedValue } = require('../../lib/obfuscation.js');
+
+//---------------------------------------------------------------------------
+// hashValue()
+//
+// Hash a secret before it becomes part of a process-wide cache key. A changed
+// secret gets a distinct entry without retaining plaintext credentials in a
+// Map key.
+//---------------------------------------------------------------------------
+function hashValue(value) {
+  return crypto.createHash('sha256').update(String(value)).digest('hex');
+}
+
+//---------------------------------------------------------------------------
+// TokenCache
+//
+// A process-wide bounded LRU cache with expiry-aware lookup and single-flight
+// acquisition. Cached token values are obfuscated, including object values
+// such as OCI token/private-key pairs. acquire() may be synchronous or async
+// and returns { value, validUntil }. Entries without a future validUntil are
+// returned but intentionally not cached.
+//---------------------------------------------------------------------------
+class TokenCache {
+  constructor(maxEntries) {
+    this._maxEntries = maxEntries;
+    this._entries = new Map();
+    this._inFlight = new Map();
+  }
+
+  async get(key, acquire, { enabled = true } = {}) {
+    if (enabled) {
+      const cached = this._entries.get(key);
+      if (cached?.validUntil > Date.now()) {
+        // Moving the hit to the end maintains insertion-order LRU semantics.
+        this._entries.delete(key);
+        this._entries.set(key, cached);
+        return {
+          value: restoreValue(cached.value),
+          validUntil: cached.validUntil,
+          isCacheHit: true,
+        };
+      }
+      if (cached) {
+        clearValue(cached.value);
+        this._entries.delete(key);
+      }
+    }
+
+    let request = this._inFlight.get(key);
+    if (!request) {
+      request = Promise.resolve().then(acquire).then((result) => {
+        if (enabled && result?.validUntil > Date.now()) {
+          this._evictLeastRecentlyUsed();
+          this._entries.set(key, {
+            value: protectValue(result.value),
+            validUntil: result.validUntil,
+          });
+        }
+        return result;
+      });
+      this._inFlight.set(key, request);
+    }
+    try {
+      const result = await request;
+      return {
+        value: result.value,
+        validUntil: result.validUntil,
+        isCacheHit: false,
+      };
+    } finally {
+      if (this._inFlight.get(key) === request) {
+        this._inFlight.delete(key);
+      }
+    }
+  }
+
+  _evictLeastRecentlyUsed() {
+    while (this._entries.size >= this._maxEntries) {
+      const oldestKey = this._entries.keys().next().value;
+      const oldestEntry = this._entries.get(oldestKey);
+      clearValue(oldestEntry.value);
+      this._entries.delete(oldestKey);
+    }
+  }
+}
+
+function protectValue(value) {
+  if (typeof value === 'string') {
+    return new ObfuscatedValue(value);
+  }
+  if (Array.isArray(value)) {
+    return value.map(protectValue);
+  }
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) =>
+      [key, protectValue(entry)]));
+  }
+  return value;
+}
+
+function restoreValue(value) {
+  if (value instanceof ObfuscatedValue) {
+    return value.get();
+  }
+  if (Array.isArray(value)) {
+    return value.map(restoreValue);
+  }
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) =>
+      [key, restoreValue(entry)]));
+  }
+  return value;
+}
+
+function clearValue(value) {
+  if (value instanceof ObfuscatedValue) {
+    value.clear();
+  } else if (Array.isArray(value)) {
+    value.forEach(clearValue);
+  } else if (value && typeof value === 'object') {
+    Object.values(value).forEach(clearValue);
+  }
+}
+
+module.exports = { TokenCache, hashValue };

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);