web_plsql 1.0.0 → 1.3.0

package/src/handler/plsql/procedureSanitize.js

@@ -1,262 +0,0 @@
-import debugModule from 'debug';
-const debug = debugModule('webplsql:procedureSanitize');
-
-import oracledb from 'oracledb';
-import z from 'zod';
-import {RequestError} from './requestError.js';
-import {errorToString} from '../../util/errorToString.js';
-
-/**
- * @typedef {import('express').Request} Request
- * @typedef {import('express').Response} Response
- * @typedef {import('oracledb').Connection} Connection
- * @typedef {import('oracledb').Result<unknown>} Result
- * @typedef {import('../../types.js').argObjType} argObjType
- * @typedef {import('../../types.js').fileUploadType} fileUploadType
- * @typedef {import('../../types.js').environmentType} environmentType
- * @typedef {import('../../types.js').configPlSqlHandlerType} configPlSqlHandlerType
- * @typedef {import('../../types.js').BindParameterConfig} BindParameterConfig
- * @typedef {import('../../util/cache.js').Cache<string>} ProcedureNameCache
- */
-
-const DEFAULT_EXCLUSION_LIST = ['sys.', 'dbms_', 'utl_', 'owa_', 'htp.', 'htf.', 'wpg_docload.', 'ctxsys.', 'mdsys.'];
-
-import {Cache} from '../../util/cache.js';
-/** @type {Cache<{valid: boolean}>} */
-const validationFunctionCache = new Cache();
-
-/**
- * Resolve the procedure name using dbms_utility.name_resolve.
- *
- * @param {string} procName - The procedure name to resolve.
- * @param {Connection} databaseConnection - The database connection.
- * @param {ProcedureNameCache} procedureNameCache - The procedure name cache.
- * @returns {Promise<string>} - The resolved canonical procedure name (SCHEMA.NAME).
- */
-const resolveProcedureName = async (procName, databaseConnection, procedureNameCache) => {
-	// Check cache
-	const cachedName = procedureNameCache.get(procName);
-	if (cachedName) {
-		debug(`resolveProcedureName: Cache hit for "${procName}" -> "${cachedName}"`);
-		return cachedName;
-	}
-
-	debug(`resolveProcedureName: Cache miss for "${procName}". Resolving in DB...`);
-
-	const sql = `
-		DECLARE
-			l_schema VARCHAR2(128);
-			l_part1  VARCHAR2(128);
-			l_part2  VARCHAR2(128);
-			l_dblink VARCHAR2(128);
-			l_part1_type NUMBER;
-			l_object_number NUMBER;
-		BEGIN
-			dbms_utility.name_resolve(
-				name => :name,
-				context => 1,
-				schema => l_schema,
-				part1 => l_part1,
-				part2 => l_part2,
-				dblink => l_dblink,
-				part1_type => l_part1_type,
-				object_number => l_object_number
-			);
-			
-			-- Reconstruct the canonical name
-			-- If it's a package procedure: schema.package.procedure
-			-- If it's a standalone procedure: schema.procedure
-			
-			IF l_part1 IS NOT NULL THEN
-				:resolved := l_schema || '.' || l_part1 || '.' || l_part2;
-			ELSE
-				:resolved := l_schema || '.' || l_part2;
-			END IF;
-		END;
-	`;
-
-	const bind = {
-		name: {dir: oracledb.BIND_IN, type: oracledb.STRING, val: procName},
-		resolved: {dir: oracledb.BIND_OUT, type: oracledb.STRING, maxSize: 400},
-	};
-
-	try {
-		const result = await databaseConnection.execute(sql, bind);
-		const {resolved} = z.object({resolved: z.string()}).parse(result.outBinds);
-
-		if (!resolved) {
-			throw new RequestError(`Could not resolve procedure name "${procName}"`);
-		}
-
-		debug(`resolveProcedureName: Resolved "${procName}" -> "${resolved}"`);
-
-		// Update cache
-		procedureNameCache.set(procName, resolved);
-
-		return resolved;
-	} catch (err) {
-		debug(`resolveProcedureName: Error resolving "${procName}"`, err);
-		// Rethrow as RequestError to indicate 404/403
-		throw new RequestError(`Procedure "${procName}" not found or not accessible.\n${errorToString(err)}`);
-	}
-};
-
-/**
- * Sanitize the procedure name.
- *
- * @param {string} procName - The procedure name.
- * @param {Connection} databaseConnection - The database connection
- * @param {configPlSqlHandlerType} options - the options for the middleware.
- * @param {ProcedureNameCache} procedureNameCache - The procedure name cache.
- * @returns {Promise<string>} Promise resolving to final procedure name.
- */
-export const sanitizeProcName = async (procName, databaseConnection, options, procedureNameCache) => {
-	debug('sanitizeProcName', procName);
-
-	// make lowercase and trim
-	let finalProcName = procName.toLowerCase().trim();
-
-	// remove special characters (basic sanity check before DB call)
-	finalProcName = removeSpecialCharacters(finalProcName);
-
-	// check for default exclusions
-	for (const i of DEFAULT_EXCLUSION_LIST) {
-		if (finalProcName.startsWith(i)) {
-			const error = `Procedure name "${procName}" is in default exclusion list "${DEFAULT_EXCLUSION_LIST.join(',')}"`;
-			debug(error);
-			throw new RequestError(error);
-		}
-	}
-
-	// check for custom exclusions
-	if (options.exclusionList && options.exclusionList.length > 0) {
-		for (const i of options.exclusionList) {
-			if (finalProcName.startsWith(i)) {
-				const error = `Procedure name "${procName}" is in custom exclusion list "${options.exclusionList.join(',')}"`;
-				debug(error);
-				throw new RequestError(error);
-			}
-		}
-	}
-
-	// Check request validation function
-	if (options.requestValidationFunction && options.requestValidationFunction.length > 0) {
-		// Note: We might want to scope this cache too, but for now let's focus on the procedure name cache.
-		// The original code used a global cache for this.
-		// For strict correctness, we should probably verify the *resolved* name,
-		// but legacy behavior checks the input name.
-		const valid = await requestValidationFunction(finalProcName, options.requestValidationFunction, databaseConnection);
-		if (!valid) {
-			const error = `Procedure name "${procName}" is not valid according to the request validation function "${options.requestValidationFunction}"`;
-			debug(error);
-			throw new RequestError(error);
-		}
-	}
-
-	// NEW: Resolve the procedure name against the database
-	// This prevents SQL injection and ensures the procedure exists
-	const resolvedName = await resolveProcedureName(finalProcName, databaseConnection, procedureNameCache);
-
-	return resolvedName;
-};
-
-/**
- * @param {string} str - string
- * @returns {string} - string
- */
-const removeSpecialCharacters = (str) => {
-	if (str === null || str === undefined) {
-		return '';
-	}
-
-	const chars = [];
-
-	for (const c of str) {
-		if ((c >= '0' && c <= '9') || (c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z') || c === '.' || c === '_' || c === '#' || c === '$') {
-			chars.push(c);
-		}
-	}
-
-	return chars.join('');
-};
-
-/**
- * @param {string} procName - The procedure name.
- * @param {string} requestValidationFunction -  The request validation function.
- * @param {Connection} databaseConnection - The database connection
- * @returns {Promise<boolean>} Promise resolving to final procedure name.
- */
-const loadRequestValid = async (procName, requestValidationFunction, databaseConnection) => {
-	/** @type {BindParameterConfig} */
-	const bind = {
-		proc: {dir: oracledb.BIND_IN, type: oracledb.STRING, val: procName},
-		valid: {dir: oracledb.BIND_OUT, type: oracledb.NUMBER},
-	};
-
-	const SQL = [
-		'DECLARE',
-		'   l_valid NUMBER := 0;',
-		'BEGIN',
-		`   IF (${requestValidationFunction}(:proc)) THEN`,
-		'      l_valid := 1;',
-		'   END IF;',
-		'   :valid := l_valid;',
-		'END;',
-	].join('\n');
-
-	/** @type {Result} */
-	let result = {};
-	try {
-		result = await databaseConnection.execute(SQL, bind);
-	} catch (err) {
-		debug('result', result);
-		const message = `Error when validating procedure name "${procName}"\n${SQL}\n${errorToString(err)}`;
-		throw new RequestError(message);
-	}
-
-	try {
-		const data = z.strictObject({valid: z.number()}).parse(result.outBinds);
-		return data.valid === 1;
-	} catch (err) {
-		debug('result', result.outBinds);
-		const message = `Internal error when parsing ${result.outBinds}\n${errorToString(err)}`;
-		throw new Error(message);
-	}
-};
-
-/**
- * Request validation function.
- *
- * @param {string} procName - The procedure name.
- * @param {string} requestValidationFunction -  The request validation function.
- * @param {Connection} databaseConnection - The database connection
- * @returns {Promise<boolean>} Promise resolving to final procedure name.
- */
-const requestValidationFunction = async (procName, requestValidationFunction, databaseConnection) => {
-	debug('requestValidationFunction', procName, requestValidationFunction);
-
-	// calculate the key
-	const key = procName.toLowerCase();
-
-	// lookup in the cache
-	const cacheEntry = validationFunctionCache.get(key);
-
-	// if we found the procedure in the cache, we return it (hitCount already incremented by get)
-	if (cacheEntry !== undefined) {
-		if (debug.enabled) {
-			debug(`requestValidationFunction: procedure "${procName}" found in cache`);
-		}
-		return cacheEntry.valid;
-	}
-
-	// load from database
-	if (debug.enabled) {
-		debug(`requestValidationFunction: procedure "${procName}" not found in cache and must be loaded`);
-	}
-	const valid = await loadRequestValid(procName, requestValidationFunction, databaseConnection);
-
-	// add to the cache
-	validationFunctionCache.set(key, {valid});
-
-	return valid;
-};

package/src/handler/plsql/procedureVariable.js

@@ -1,54 +0,0 @@
-/*
- *	Invoke the Oracle procedure and return the raw content of the page
- */
-
-import debugModule from 'debug';
-const debug = debugModule('webplsql:procedureVariable');
-
-import oracledb from 'oracledb';
-
-/**
- * @typedef {import('express').Request} Request
- * @typedef {import('oracledb').Connection} Connection
- * @typedef {import('oracledb').Result<unknown>} Result
- * @typedef {import('../../types.js').configPlSqlHandlerType} configPlSqlHandlerType
- * @typedef {import('../../types.js').argObjType} argObjType
- * @typedef {import('../../types.js').BindParameterConfig} BindParameterConfig
- */
-
-/**
- *	Get the sql statement and bindings for the procedure to execute for a variable number of arguments
- *	@param {Request} _req - The req object represents the HTTP request. (only used for debugging)
- *	@param {string} procName - The procedure to execute
- *	@param {argObjType} argObj - The arguments to pass to the procedure
- *	@returns {{sql: string; bind: BindParameterConfig}} - The SQL statement and bindings for the procedure to execute
- */
-export const getProcedureVariable = (_req, procName, argObj) => {
-	if (debug.enabled) {
-		debug(`getProcedureVariable: ${procName} arguments=`, argObj);
-	}
-
-	const names = [];
-	const values = [];
-
-	for (const key in argObj) {
-		const value = argObj[key];
-		if (typeof value === 'string') {
-			names.push(key);
-			values.push(value);
-		} else if (Array.isArray(value)) {
-			value.forEach((item) => {
-				names.push(key);
-				values.push(item);
-			});
-		}
-	}
-
-	return {
-		sql: `${procName}(:argnames, :argvalues)`,
-		bind: {
-			argnames: {dir: oracledb.BIND_IN, type: oracledb.STRING, val: names},
-			argvalues: {dir: oracledb.BIND_IN, type: oracledb.STRING, val: values},
-		},
-	};
-};

package/src/handler/plsql/request.js

@@ -1,124 +0,0 @@
-/*
- *	Process the http request
- */
-
-import debugModule from 'debug';
-const debug = debugModule('webplsql:request');
-
-import util from 'node:util';
-import {invokeProcedure} from './procedure.js';
-import {getCGI} from './cgi.js';
-import {getFiles} from './upload.js';
-import {RequestError} from './requestError.js';
-import {isStringOrArrayOfString} from '../../util/type.js';
-
-/**
- * @typedef {import('express').Request} Request
- * @typedef {import('express').Response} Response
- * @typedef {import('oracledb').Pool} Pool
- * @typedef {import('oracledb').Connection} Connection
- * @typedef {import('../../types.js').argObjType} argObjType
- * @typedef {import('../../types.js').configPlSqlHandlerType} configPlSqlHandlerType
- * @typedef {import('../../util/cache.js').Cache<string>} ProcedureNameCache
- * @typedef {import('../../util/cache.js').Cache<import('./procedureNamed.js').argsType>} ArgumentCache
- */
-
-/**
- * Execute the request
- *
- * @param {Request} req - The req object represents the HTTP request.
- * @param {Response} res - The res object represents the HTTP response that an Express app sends when it gets an HTTP request.
- * @param {configPlSqlHandlerType} options - the options for the middleware.
- * @param {Pool} connectionPool - The connection pool.
- * @param {ProcedureNameCache} procedureNameCache - The procedure name cache.
- * @param {ArgumentCache} argumentCache - The argument cache.
- * @returns {Promise<void>} - Promise resolving to th page
- */
-export const processRequest = async (req, res, options, connectionPool, procedureNameCache, argumentCache) => {
-	debug('processRequest: ENTER');
-
-	//
-	if (Array.isArray(req.params.name)) {
-		console.warn(`processRequest: WARNING: the req.params.name is not a string but an array of string: ${req.params.name.join(',')}`);
-	}
-
-	// open database connection
-	const connection = await connectionPool.getConnection();
-
-	// Get the CGI
-	const cgiObj = getCGI(req, options.documentTable ?? '', options.cgi ?? {});
-	debug('processRequest: cgiObj=', cgiObj);
-
-	// Does the request contain any files
-	const filesToUpload = getFiles(req);
-	debug('processRequest: filesToUpload=', filesToUpload);
-
-	// Add the query properties
-	/** @type {argObjType} */
-	const argObj = {};
-	Object.assign(argObj, req.query);
-
-	// For add the files that must be uploaded, we now copy the actual filename to the appropriate parameter to the invoked procedure.
-	filesToUpload.reduce((aggregator, file) => {
-		aggregator[file.fieldname] = file.filename;
-		return aggregator;
-	}, argObj);
-
-	// Does the request contain a body
-	Object.assign(argObj, normalizeBody(req));
-	debug('processRequest: argObj=', argObj);
-
-	// invoke the Oracle procedure and get the page contenst
-	await invokeProcedure(req, res, argObj, cgiObj, filesToUpload, options, connection, procedureNameCache, argumentCache);
-
-	// transaction mode
-	if (options.transactionMode === 'rollback') {
-		debug('transactionMode: rollback');
-		await connection.rollback();
-	} else if (typeof options.transactionMode === 'function') {
-		debug('transactionMode: callback');
-		const procName = Array.isArray(req.params.name) ? req.params.name[0] : req.params.name;
-		const result = options.transactionMode(connection, procName ?? '');
-		debug('transactionMode: callback restult', result);
-		if (result && typeof result.then === 'function') {
-			await result;
-		}
-	} else {
-		debug('transactionMode: commit');
-		await connection.commit();
-	}
-
-	// close database connection
-	await connection.release();
-
-	debug('processRequest: EXIT');
-};
-
-/**
- *	Normalize the body by making sure that only "simple" parameters and no nested objects are submitted
- *	@param {Request} req - The req object represents the HTTP request.
- *	@returns {Record<string, string | string[]>} - The normalized body.
- */
-const normalizeBody = (req) => {
-	/** @type {Record<string, string | string[]>} */
-	const args = {};
-
-	/* v8 ignore else - body validation */
-	if (typeof req.body === 'object' && req.body !== null) {
-		for (const key in req.body) {
-			// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access
-			const value = req.body[key];
-			/* v8 ignore else - type validation */
-			if (isStringOrArrayOfString(value)) {
-				args[key] = value;
-			} else {
-				/* v8 ignore next - invalid body type */
-				throw new RequestError(
-					`The element "${key}" in the body is not a string or an array of strings!\n${util.inspect(req.body, {showHidden: false, depth: null, colors: false})}`,
-				);
-			}
-		}
-	}
-
-	return args;
-};

package/src/handler/plsql/requestError.js

@@ -1,23 +0,0 @@
-/*
- *	RequestError
- */
-
-export class RequestError extends Error {
-	/** @type {Date} */
-	timestamp;
-
-	/**
-	 * @param {string} message - The error message.
-	 */
-	constructor(message) {
-		super(message);
-
-		// Maintains proper stack trace for where our error was thrown (only available on V8)
-		if (Error.captureStackTrace) {
-			Error.captureStackTrace(this, RequestError);
-		}
-
-		// Custom debugging information
-		this.timestamp = new Date();
-	}
-}

package/src/handler/plsql/sendResponse.js

@@ -1,136 +0,0 @@
-/*
- *	Page the raw page content and return the content to the client
- */
-
-import debugModule from 'debug';
-const debug = debugModule('webplsql:sendResponse');
-
-import stream from 'node:stream';
-import {getBlock} from '../../util/trace.js';
-
-/**
- * @typedef {import('express').Request} Request
- * @typedef {import('express').Response} Response
- * @typedef {import('express').CookieOptions} CookieOptions
- * @typedef {import('../../types.js').pageType} pageType
- * @typedef {import('../../types.js').cookieType} cookieType
- */
-
-/**
- *	Send "default" response to the browser
- *	@param {Request} _req - The req object represents the HTTP request.
- *	@param {Response} res - The res object represents the HTTP response that an Express app sends when it gets an HTTP request.
- *	@param {pageType} page - The page to send.
- *	@returns {Promise<void>}
- */
-export const sendResponse = async (_req, res, page) => {
-	/** @type {string[]} */
-	const debugText = [];
-
-	// Send the "cookies"
-	page.head.cookies.forEach((cookie) => {
-		if (debug.enabled) {
-			debugText.push(`res.cookie: name="${cookie.name}" value="${cookie.value}" options=${JSON.stringify(cookie.options)}`);
-		}
-
-		res.cookie(cookie.name, cookie.value, cookie.options);
-	});
-
-	// If there is a "redirectLocation" header, we immediately redirect and return
-	if (typeof page.head.redirectLocation === 'string' && page.head.redirectLocation.length > 0) {
-		if (debug.enabled) {
-			debugText.push(`res.redirect(302, "${page.head.redirectLocation}")`);
-			debug(getBlock('RESPONSE', debugText.join('\n')));
-		}
-
-		res.redirect(302, page.head.redirectLocation);
-		return;
-	}
-
-	// Send all the "otherHeaders"
-	for (const key in page.head.otherHeaders) {
-		if (debug.enabled) {
-			debugText.push(`res.set("${key}", "${page.head.otherHeaders[key]}")`);
-		}
-
-		res.set(key, page.head.otherHeaders[key]);
-	}
-
-	// If this is a file download, we eventually set the "Content-Type" and the file content and then return.
-	if (page.file.fileType === 'B' || page.file.fileType === 'F') {
-		/** @type {Record<string, string>} */
-		const headers = {};
-
-		if (typeof page.head.contentType === 'string' && page.head.contentType.length > 0) {
-			headers['Content-Type'] = page.head.contentType;
-		}
-
-		if (typeof page.file.fileSize === 'number' && page.file.fileSize > 0) {
-			headers['Content-Length'] = page.file.fileSize.toString();
-		}
-
-		if (Object.keys(headers).length > 0) {
-			if (debug.enabled) {
-				debugText.push(`res.writeHead(200, ${JSON.stringify(headers)})`);
-			}
-			res.writeHead(200, headers);
-		}
-
-		// Check if fileBlob is a stream
-		if (page.file.fileBlob instanceof stream.Readable) {
-			if (debug.enabled) {
-				debugText.push(`res.pipe("${page.file.fileType}") - streaming`);
-				debug(getBlock('RESPONSE', debugText.join('\n')));
-			}
-
-			/** @type {Promise<void>} */
-			const streamComplete = new Promise((resolve, reject) => {
-				if (page.file.fileBlob instanceof stream.Readable) {
-					page.file.fileBlob.pipe(res);
-					page.file.fileBlob.on('end', () => resolve());
-					/* v8 ignore next - error handler */
-					page.file.fileBlob.on('error', (/** @type {Error} */ err) => reject(err));
-					/* v8 ignore next - error handler */
-					res.on('close', () => resolve());
-				}
-			});
-			await streamComplete;
-		} else {
-			if (debug.enabled) {
-				debugText.push(`res.end("${page.file.fileType}") - buffer`);
-				debug(getBlock('RESPONSE', debugText.join('\n')));
-			}
-
-			res.end(page.file.fileBlob, 'binary');
-		}
-		return;
-	}
-
-	// Is the a "contentType" header
-	if (typeof page.head.contentType === 'string' && page.head.contentType.length > 0) {
-		if (debug.enabled) {
-			debugText.push(`res.set("Content-Type", "${page.head.contentType}")`);
-		}
-
-		res.set('Content-Type', page.head.contentType);
-	}
-
-	// If we have a "Status" header, we send the header and then return.
-	if (typeof page.head.statusCode === 'number') {
-		if (debug.enabled) {
-			debugText.push(`res.status(page.head.statusCode).send("${page.head.statusDescription}")`);
-			debug(getBlock('RESPONSE', debugText.join('\n')));
-		}
-
-		res.status(page.head.statusCode).send(page.head.statusDescription);
-		return;
-	}
-
-	// Send the body
-	if (debug.enabled) {
-		debugText.push(`${'-'.repeat(60)}\n${page.body}`);
-		debug(getBlock('RESPONSE', debugText.join('\n')));
-	}
-
-	res.send(page.body);
-};

package/src/handler/plsql/stream.js

@@ -1,28 +0,0 @@
-import stream from 'node:stream';
-
-/**
- *	Convert a readable stream to a buffer.
- *
- * @param {stream.Readable} readable - The readable stream.
- * @returns {Promise<Buffer>} The buffer.
- */
-export const streamToBuffer = async (readable) => {
-	return new Promise((resolve, reject) => {
-		/** @type {Buffer[]} */
-		const buffers = [];
-
-		readable.on('data', (buffer) => {
-			// eslint-disable-next-line @typescript-eslint/no-unsafe-argument
-			buffers.push(buffer);
-		});
-
-		readable.on('end', () => {
-			resolve(Buffer.concat(buffers));
-		});
-
-		readable.on('error', (err) => {
-			/* v8 ignore next - error handler */
-			reject(err);
-		});
-	});
-};