@harperfast/harper 5.0.0-alpha.10 → 5.0.0-beta.1

package/security/certificateVerification/verificationConfig.ts

@@ -0,0 +1,138 @@
+/**
+ * Configuration parsing and default values for certificate verification
+ */
+
+import { loggerWithTag } from '../../utility/logging/logger.ts';
+import { packageJson } from '../../utility/packageUtils.js';
+import type { CertificateVerificationConfig } from './types.ts';
+import { validateAndParseCertificateVerificationConfig } from './configValidation.ts';
+
+const logger = loggerWithTag('cert-verification-config');
+
+// Constants for hardcoded values
+export const CRL_DEFAULT_VALIDITY_PERIOD = 7 * 24 * 60 * 60 * 1000; // 7 days in milliseconds
+export const ERROR_CACHE_TTL = 300000; // 5 minutes for error caching
+export const CRL_USER_AGENT = `Harper/${packageJson.version} CRL-Client`;
+
+// Configuration cache to avoid redundant parsing on every certificate verification
+// Using WeakMap to prevent memory leaks from holding strong references to config objects
+// This allows garbage collection of config objects when they're no longer referenced elsewhere
+const configCache = new WeakMap<Record<string, any>, CertificateVerificationConfig | false>();
+let lastPrimitiveConfig: boolean | null | undefined = null;
+let lastPrimitiveResult: CertificateVerificationConfig | false | null = null;
+
+// Track validation errors to prevent repeated error logging and provide graceful degradation
+// Maps config object to the error that occurred during validation
+const validationErrorCache = new WeakMap<Record<string, any>, Error>();
+let lastPrimitiveValidationError: Error | null = null;
+
+/**
+ * Cached version of getCertificateVerificationConfig to avoid redundant parsing
+ * This is the recommended function to use in hot paths like certificate verification.
+ *
+ * MEMORY SAFETY:
+ * - Uses WeakMap for object configs to prevent memory leaks
+ * - Config objects can be garbage collected when no longer referenced elsewhere
+ * - Primitive values (boolean, null, undefined) use simple reference equality
+ * - No strong references held to config objects, preventing memory accumulation
+ *
+ * ERROR HANDLING:
+ * - Invalid config causes validation errors to be thrown on first access
+ * - Validation errors are logged once and then cached
+ * - Subsequent accesses with the same invalid config return false (disabled) to prevent
+ *   repeated error logging and allow the application to continue running
+ * - This provides fail-safe behavior: invalid security config defaults to disabled
+ *   rather than crashing on every request
+ *
+ * @param mtlsConfig - The mTLS configuration from env.get()
+ * @returns Configuration object or false if verification is disabled or invalid
+ */
+export function getCachedCertificateVerificationConfig(
+	mtlsConfig?: boolean | Record<string, any> | null
+): false | CertificateVerificationConfig {
+	// Handle primitive values (boolean, null, undefined) with simple caching
+	if (typeof mtlsConfig === 'boolean' || mtlsConfig == null) {
+		// Check if we've already seen a validation error for this primitive config
+		if (mtlsConfig === lastPrimitiveConfig && lastPrimitiveValidationError) {
+			logger.trace?.('Using cached validation error result (primitive) - returning disabled');
+			return false;
+		}
+
+		if (mtlsConfig === lastPrimitiveConfig && lastPrimitiveResult !== null) {
+			logger.trace?.('Using cached certificate verification config (primitive)');
+			return lastPrimitiveResult;
+		}
+
+		logger.trace?.('Parsing and caching certificate verification config (primitive)');
+		lastPrimitiveConfig = mtlsConfig as boolean | null | undefined;
+		try {
+			lastPrimitiveResult = getCertificateVerificationConfig(mtlsConfig);
+			lastPrimitiveValidationError = null; // Clear any previous error
+			return lastPrimitiveResult;
+		} catch (error) {
+			// Cache the validation error to prevent repeated logging
+			lastPrimitiveValidationError = error as Error;
+			logger.error?.(
+				`Certificate verification config validation failed - defaulting to disabled: ${(error as Error).message}`
+			);
+			return false; // Fail-safe: invalid config = disabled verification
+		}
+	}
+
+	// Check for cached validation error
+	const cachedError = validationErrorCache.get(mtlsConfig);
+	if (cachedError) {
+		logger.trace?.('Using cached validation error result (object) - returning disabled');
+		return false;
+	}
+
+	const cached = configCache.get(mtlsConfig);
+	if (cached !== undefined) {
+		logger.trace?.('Using cached certificate verification config (object)');
+		return cached;
+	}
+
+	// Cache miss: parse and store the result
+	logger.trace?.('Parsing and caching certificate verification config (object)');
+	try {
+		const result = getCertificateVerificationConfig(mtlsConfig);
+		configCache.set(mtlsConfig, result);
+		return result;
+	} catch (error) {
+		// Cache the validation error to prevent repeated logging
+		validationErrorCache.set(mtlsConfig, error as Error);
+		logger.error?.(
+			`Certificate verification config validation failed - defaulting to disabled: ${(error as Error).message}`
+		);
+		return false; // Fail-safe: invalid config = disabled verification
+	}
+}
+
+/**
+ * Determine if certificate verification should be performed based on configuration
+ * @param mtlsConfig - The mTLS configuration (can be boolean or object)
+ * @returns Configuration object or false if verification is disabled
+ */
+function getCertificateVerificationConfig(
+	mtlsConfig?: boolean | Record<string, any> | null
+): false | CertificateVerificationConfig {
+	logger.trace?.(`getCertificateVerificationConfig called with: ${JSON.stringify({ mtlsConfig })}`);
+
+	if (!mtlsConfig) return false;
+
+	const verificationConfig = mtlsConfig === true ? undefined : mtlsConfig.certificateVerification;
+	logger.trace?.(`Certificate verification config: ${JSON.stringify({ verificationConfig })}`);
+
+	// Default to disabled for initial rollout to allow intentional real-world testing
+	// Users must explicitly enable certificate verification with certificateVerification: true or config object
+	if (verificationConfig == null || verificationConfig === false) return false;
+
+	// Pass through validator for enabled cases (true or object)
+	// Convert true to empty object so validator applies all defaults
+	// This ensures we always get a complete config with crl and ocsp defaults
+	const configToValidate = verificationConfig === true ? {} : verificationConfig;
+
+	// Let validation errors propagate up to getCachedCertificateVerificationConfig
+	// which will log them once and cache the error
+	return validateAndParseCertificateVerificationConfig(configToValidate);
+}

package/security/certificateVerification/verificationUtils.ts

@@ -0,0 +1,447 @@
+/**
+ * Shared utilities for certificate verification
+ */
+
+import { createHash } from 'node:crypto';
+import * as pkijs from 'pkijs';
+import * as asn1js from 'asn1js';
+import { loggerWithTag } from '../../utility/logging/logger.ts';
+import { table } from '../../resources/databases.ts';
+import type { PeerCertificate, CertificateChainEntry } from './types.ts';
+
+const logger = loggerWithTag('cert-verification-utils');
+
+/**
+ * Convert a buffer to PEM format
+ * @param buffer - Certificate data as buffer
+ * @param type - Certificate type (e.g., 'CERTIFICATE')
+ * @returns PEM formatted string
+ */
+export function bufferToPem(buffer: Buffer, type: string): string {
+	const base64 = buffer.toString('base64');
+	const lines = [`-----BEGIN ${type}-----`];
+
+	// Split into 64-char lines
+	for (let i = 0; i < base64.length; i += 64) {
+		lines.push(base64.substring(i, i + 64));
+	}
+
+	lines.push(`-----END ${type}-----`);
+	return lines.join('\n');
+}
+
+/**
+ * Extract certificate chain from peer certificate object
+ * @param peerCertificate - Peer certificate object from TLS connection
+ * @returns Certificate chain with issuer relationships
+ */
+export function extractCertificateChain(peerCertificate: PeerCertificate): CertificateChainEntry[] {
+	const chain: CertificateChainEntry[] = [];
+	let current = peerCertificate;
+
+	while (current?.raw) {
+		const entry: CertificateChainEntry = { cert: current.raw };
+
+		// Get issuer if available and different from self
+		if (current.issuerCertificate && current.issuerCertificate !== current && current.issuerCertificate.raw) {
+			entry.issuer = current.issuerCertificate.raw;
+		}
+
+		chain.push(entry);
+
+		// Move to next in chain
+		if (current.issuerCertificate && current.issuerCertificate !== current) {
+			current = current.issuerCertificate;
+		} else {
+			break;
+		}
+	}
+
+	return chain;
+}
+
+/**
+ * Extract CRL Distribution Points from a certificate using PKI.js
+ * @param certPem - Certificate in PEM format
+ * @returns Array of CRL distribution point URLs
+ */
+export function extractCRLDistributionPoints(certPem: string): string[] {
+	try {
+		// Parse the certificate using PKI.js
+		const certBuffer = pemToBuffer(certPem);
+		const cert = pkijs.Certificate.fromBER(certBuffer);
+
+		// Look for CRL Distribution Points extension (OID: 2.5.29.31)
+		const crlDistExt = cert.extensions?.find((ext) => ext.extnID === '2.5.29.31');
+
+		if (!crlDistExt) {
+			logger.debug?.('Certificate has no CRL Distribution Points extension');
+			return [];
+		}
+
+		// Parse the extension value
+		const asn1 = asn1js.fromBER(crlDistExt.extnValue.valueBlock.valueHexView);
+		if (asn1.offset === -1) {
+			throw new Error('Failed to parse ASN.1 structure in CRL Distribution Points extension');
+		}
+
+		const crlDistPoints = new pkijs.CRLDistributionPoints({
+			schema: asn1.result,
+		});
+
+		const distributionPoints: string[] = [];
+
+		// Extract distribution point URLs
+		for (const distPoint of crlDistPoints.distributionPoints) {
+			if (distPoint.distributionPoint && Array.isArray(distPoint.distributionPoint)) {
+				// Handle the actual PKI.js structure where distributionPoint is an array
+				for (const dp of distPoint.distributionPoint) {
+					if (dp.type === 6 && typeof dp.value === 'string') {
+						// uniformResourceIdentifier
+						const url = dp.value;
+						if (url.startsWith('http://') || url.startsWith('https://')) {
+							distributionPoints.push(url);
+						}
+					}
+				}
+			}
+		}
+
+		logger.debug?.(`Found ${distributionPoints.length} CRL distribution points: ${distributionPoints}`);
+		return distributionPoints;
+	} catch (error) {
+		// Parsing failures are treated as "no CRL URLs available"
+		// Rationale: The certificate was already validated by Node.js TLS (signature, trust chain)
+		// If PKI.js can't parse it, it's likely a library incompatibility or unsupported extension format
+		// Not a security issue since TLS already validated the cert - we just can't extract revocation URLs
+		// The higher-level fail-open/fail-closed configuration determines final behavior when no URLs found
+		logger.warn?.(`Failed to extract CRL distribution points: ${error}`);
+		return [];
+	}
+}
+
+/**
+ * Extract both CRL and OCSP URLs from a certificate in a single parse operation
+ * @param certPem - Certificate in PEM format
+ * @returns Object containing arrays of CRL and OCSP URLs
+ */
+export function extractRevocationUrls(certPem: string): { crlUrls: string[]; ocspUrls: string[] } {
+	try {
+		// Parse the certificate using PKI.js (single parse for both URL types)
+		const certBuffer = pemToBuffer(certPem);
+		const cert = pkijs.Certificate.fromBER(certBuffer);
+
+		const crlUrls: string[] = [];
+		const ocspUrls: string[] = [];
+
+		// Single pass through extensions to extract both CRL and OCSP URLs
+		for (const ext of cert.extensions || []) {
+			if (ext.extnID === '2.5.29.31') {
+				// CRL Distribution Points extension
+				try {
+					const asn1 = asn1js.fromBER(ext.extnValue.valueBlock.valueHexView);
+					if (asn1.offset !== -1) {
+						const crlDistPoints = new pkijs.CRLDistributionPoints({
+							schema: asn1.result,
+						});
+
+						// Extract CRL distribution point URLs
+						for (const distPoint of crlDistPoints.distributionPoints) {
+							if (distPoint.distributionPoint && Array.isArray(distPoint.distributionPoint)) {
+								// Handle the actual PKI.js structure where distributionPoint is an array
+								for (const dp of distPoint.distributionPoint) {
+									if (dp.type === 6 && typeof dp.value === 'string') {
+										// uniformResourceIdentifier
+										const url = dp.value;
+										if (url.startsWith('http://') || url.startsWith('https://')) {
+											crlUrls.push(url);
+										}
+									}
+								}
+							}
+						}
+					}
+				} catch (crlError) {
+					logger.warn?.(`Failed to parse CRL Distribution Points extension: ${crlError}`);
+				}
+			} else if (ext.extnID === '1.3.6.1.5.5.7.1.1') {
+				// Authority Information Access extension
+				try {
+					const asn1 = asn1js.fromBER(ext.extnValue.valueBlock.valueHexView);
+					if (asn1.offset !== -1 && asn1.result instanceof asn1js.Sequence) {
+						for (const accessDesc of asn1.result.valueBlock.value) {
+							if (accessDesc instanceof asn1js.Sequence && accessDesc.valueBlock.value.length >= 2) {
+								const accessMethod = accessDesc.valueBlock.value[0];
+								const accessLocation = accessDesc.valueBlock.value[1];
+
+								// Check if accessMethod is OCSP (OID 1.3.6.1.5.5.7.48.1)
+								if (
+									accessMethod instanceof asn1js.ObjectIdentifier &&
+									accessMethod.valueBlock.toString() === '1.3.6.1.5.5.7.48.1'
+								) {
+									// Check if accessLocation is a URI (context tag 6)
+									if (accessLocation.idBlock.tagNumber === 6) {
+										const url = String.fromCharCode(
+											...Array.from((accessLocation.valueBlock as any).valueHexView as Uint8Array)
+										);
+										if (url.startsWith('http://') || url.startsWith('https://')) {
+											ocspUrls.push(url);
+										}
+									}
+								}
+							}
+						}
+					}
+				} catch (ocspError) {
+					logger.warn?.(`Failed to parse Authority Information Access extension: ${ocspError}`);
+				}
+			}
+		}
+
+		logger.debug?.(`Found ${crlUrls.length} CRL distribution points and ${ocspUrls.length} OCSP responder URLs`);
+		return { crlUrls, ocspUrls };
+	} catch (error) {
+		// Parsing failures are treated as "no revocation URLs available"
+		// Rationale: The certificate was already validated by Node.js TLS (signature, trust chain)
+		// If PKI.js can't parse it, it's likely a library incompatibility or unsupported extension format
+		// Not a security issue since TLS already validated the cert - we just can't extract revocation URLs
+		// The higher-level fail-open/fail-closed configuration determines final behavior when no URLs found
+		logger.warn?.(`Failed to extract revocation URLs: ${error}`);
+		return { crlUrls: [], ocspUrls: [] };
+	}
+}
+
+/**
+ * Extract OCSP responder URLs from a certificate
+ * @param certPem - Certificate in PEM format
+ * @returns Array of OCSP responder URLs
+ */
+export function extractOCSPUrls(certPem: string): string[] {
+	try {
+		// Parse the certificate using PKI.js
+		const certBuffer = pemToBuffer(certPem);
+		const cert = pkijs.Certificate.fromBER(certBuffer);
+
+		// Look for Authority Information Access extension (OID: 1.3.6.1.5.5.7.1.1)
+		const aiaExt = cert.extensions?.find((ext) => ext.extnID === '1.3.6.1.5.5.7.1.1');
+
+		if (!aiaExt) {
+			logger.debug?.('Certificate has no Authority Information Access extension');
+			return [];
+		}
+
+		// Parse the extension value using asn1js
+		const asn1 = asn1js.fromBER(aiaExt.extnValue.valueBlock.valueHexView);
+		if (asn1.offset === -1) {
+			throw new Error('Failed to parse ASN.1 structure in Authority Information Access extension');
+		}
+
+		const ocspUrls: string[] = [];
+
+		// The AIA extension contains a sequence of AccessDescription entries
+		// Each AccessDescription has: accessMethod (OID) and accessLocation (GeneralName)
+		if (asn1.result instanceof asn1js.Sequence) {
+			for (const accessDesc of asn1.result.valueBlock.value) {
+				if (accessDesc instanceof asn1js.Sequence && accessDesc.valueBlock.value.length >= 2) {
+					const accessMethod = accessDesc.valueBlock.value[0];
+					const accessLocation = accessDesc.valueBlock.value[1];
+
+					// Check if accessMethod is OCSP (OID 1.3.6.1.5.5.7.48.1)
+					if (
+						accessMethod instanceof asn1js.ObjectIdentifier &&
+						accessMethod.valueBlock.toString() === '1.3.6.1.5.5.7.48.1'
+					) {
+						// Check if accessLocation is a URI (context tag 6)
+						if (accessLocation.idBlock.tagNumber === 6) {
+							const url = String.fromCharCode(
+								...Array.from((accessLocation.valueBlock as any).valueHexView as Uint8Array)
+							);
+							if (url.startsWith('http://') || url.startsWith('https://')) {
+								ocspUrls.push(url);
+							}
+						}
+					}
+				}
+			}
+		}
+
+		logger.debug?.(`Found ${ocspUrls.length} OCSP responder URLs: ${ocspUrls}`);
+		return ocspUrls;
+	} catch (error) {
+		logger.error?.(`Failed to extract OCSP URLs: ${error}`);
+		return [];
+	}
+}
+
+/**
+ * Convert PEM string to buffer for PKI.js parsing
+ * @param pem - PEM formatted certificate
+ * @returns Buffer containing certificate data
+ */
+export function pemToBuffer(pem: string): ArrayBuffer {
+	// Remove PEM headers and whitespace
+	const base64 = pem
+		.replace(/-----BEGIN [^-]+-----/g, '')
+		.replace(/-----END [^-]+-----/g, '')
+		.replace(/\s/g, '');
+
+	// Convert to buffer
+	const binaryString = atob(base64);
+	const buffer = new ArrayBuffer(binaryString.length);
+	const view = new Uint8Array(buffer);
+
+	for (let i = 0; i < binaryString.length; i++) {
+		view[i] = binaryString.charCodeAt(i);
+	}
+
+	return buffer;
+}
+
+/**
+ * Create a cache key for certificate verification
+ * @param certPem - Certificate in PEM format
+ * @param issuerPem - Issuer certificate in PEM format
+ * @param method - Verification method (ocsp, crl)
+ * @param additionalData - Additional data to include in hash
+ * @returns Cache key string
+ */
+export function createCacheKey(
+	certPem: string,
+	issuerPem: string,
+	method: 'ocsp' | 'crl',
+	additionalData?: Record<string, any>
+): string {
+	const cacheData = {
+		certPem,
+		issuerPem,
+		method,
+		...additionalData,
+	};
+	const cacheKeyHash = createHash('sha256').update(JSON.stringify(cacheData)).digest('hex');
+	return `${method}:${cacheKeyHash}`;
+}
+
+/**
+ * Create a cache key for CRL storage
+ * @param distributionPoint - CRL distribution point URL
+ * @returns Cache key string
+ */
+export function createCRLCacheKey(distributionPoint: string): string {
+	const hash = createHash('sha256').update(distributionPoint).digest('hex');
+	return `crl:${hash}`;
+}
+
+/**
+ * Create a composite ID for revoked certificate lookup
+ * @param issuerKeyId - Issuer key identifier or DN hash
+ * @param serialNumber - Certificate serial number
+ * @returns Composite ID string
+ */
+export function createRevokedCertificateId(issuerKeyId: string, serialNumber: string): string {
+	return `${issuerKeyId}:${serialNumber}`;
+}
+
+/**
+ * Extract serial number from a certificate
+ * @param certPem - Certificate in PEM format
+ * @returns Certificate serial number as string
+ */
+export function extractSerialNumber(certPem: string): string {
+	try {
+		const certBuffer = pemToBuffer(certPem);
+		const cert = pkijs.Certificate.fromBER(certBuffer);
+
+		// Convert serial number to string
+		const serialNumber = cert.serialNumber.valueBlock.valueHexView;
+		return Array.from(serialNumber)
+			.map((b) => b.toString(16).padStart(2, '0'))
+			.join('');
+	} catch (error) {
+		logger.error?.(`Failed to extract serial number: ${error}`);
+		throw new Error(`Failed to extract certificate serial number: ${error.message}`);
+	}
+}
+
+/**
+ * Extract issuer key identifier from a certificate
+ * @param certPem - Certificate in PEM format
+ * @returns Issuer key identifier as hex string, or hash of issuer DN if not available
+ */
+export function extractIssuerKeyId(certPem: string): string {
+	try {
+		const certBuffer = pemToBuffer(certPem);
+		const cert = pkijs.Certificate.fromBER(certBuffer);
+
+		// Look for Authority Key Identifier extension (OID: 2.5.29.35)
+		const akiExt = cert.extensions?.find((ext) => ext.extnID === '2.5.29.35');
+
+		if (akiExt) {
+			try {
+				// Parse the extension value manually since parsedValue may be undefined for Ed25519 certs
+				const asn1 = asn1js.fromBER(akiExt.extnValue.valueBlock.valueHexView);
+				if (asn1.offset !== -1) {
+					const aki = new pkijs.AuthorityKeyIdentifier({
+						schema: asn1.result,
+					});
+
+					if (aki.keyIdentifier) {
+						const keyId = aki.keyIdentifier.valueBlock.valueHexView;
+						return Array.from(keyId)
+							.map((b) => b.toString(16).padStart(2, '0'))
+							.join('');
+					}
+				}
+			} catch (parseError) {
+				logger.debug?.(`Failed to parse Authority Key Identifier: ${parseError}, falling back to hash`);
+			}
+		}
+
+		// Fall back to hash of issuer DN
+		const issuerDN = cert.issuer.typesAndValues.map((tv) => `${tv.type}=${tv.value.valueBlock.value}`).join(',');
+
+		return createHash('sha256').update(issuerDN).digest('hex');
+	} catch (error) {
+		logger.error?.(`Failed to extract issuer key ID: ${error}`);
+		throw new Error(`Failed to extract issuer key ID: ${error.message}`);
+	}
+}
+
+/**
+ * Get shared certificate verification cache table
+ * @returns Harper table instance for certificate verification cache
+ */
+// Cache the certificate cache table instance to avoid recreating it
+let certificateCacheTable: ReturnType<typeof table> | null = null;
+
+export function getCertificateCacheTable() {
+	if (!certificateCacheTable) {
+		certificateCacheTable = table({
+			table: 'hdb_certificate_cache',
+			database: 'system',
+			attributes: [
+				{
+					name: 'certificate_id',
+					isPrimaryKey: true,
+				},
+				{
+					name: 'status', // 'good', 'revoked', 'unknown'
+				},
+				{
+					name: 'reason',
+				},
+				{
+					name: 'checked_at',
+				},
+				{
+					name: 'expiresAt',
+					expiresAt: true,
+					indexed: true,
+				},
+				{
+					name: 'method', // 'ocsp' or 'crl'
+				},
+			],
+		});
+	}
+	return certificateCacheTable;
+}

package/security/cryptoHash.js

@@ -0,0 +1,42 @@
+'use strict';
+
+const crypto = require('crypto');
+
+const CRYPTO_ALGORITHM = 'aes-256-cbc';
+const KEY_BYTE_LENGTH = 32;
+const IV_BYTE_LENGTH = 16;
+const KEY_STRING_LENGTH = 64;
+const IV_STRING_LENGTH = 32;
+const ENCRYPTED_STRING_START = KEY_STRING_LENGTH + IV_STRING_LENGTH;
+
+module.exports = {
+	encrypt,
+	decrypt,
+};
+
+function encrypt(text) {
+	let key = crypto.randomBytes(KEY_BYTE_LENGTH);
+	let iv = crypto.randomBytes(IV_BYTE_LENGTH);
+
+	let cipher = crypto.createCipheriv(CRYPTO_ALGORITHM, Buffer.from(key), iv);
+	let encrypted = cipher.update(text);
+	encrypted = Buffer.concat([encrypted, cipher.final()]);
+
+	let keyString = key.toString('hex');
+	let ivString = iv.toString('hex');
+	let encryptedString = encrypted.toString('hex');
+	return keyString + ivString + encryptedString;
+}
+
+function decrypt(text) {
+	let keyString = text.substr(0, KEY_STRING_LENGTH);
+	let ivString = text.substr(KEY_STRING_LENGTH, IV_STRING_LENGTH);
+	let encrptedString = text.substr(ENCRYPTED_STRING_START, text.length);
+
+	let iv = Buffer.from(ivString, 'hex');
+	let encryptedText = Buffer.from(encrptedString, 'hex');
+	let decipher = crypto.createDecipheriv(CRYPTO_ALGORITHM, Buffer.from(keyString, 'hex'), iv);
+	let decrypted = decipher.update(encryptedText);
+	decrypted = Buffer.concat([decrypted, decipher.final()]);
+	return decrypted.toString();
+}

package/security/data_objects/PermissionAttributeResponseObject.js

@@ -0,0 +1,15 @@
+'use strict';
+
+class PermissionAttributeResponseObject {
+	/**
+	 * Used to track role-based, attribute-level permission issues related to an incoming API request/operation
+	 * @param attrName {String} name of the attribute with a permission restriction
+	 * @param requiredPerms {Array} array of CRU perms that are required on attr for operation
+	 */
+	constructor(attrName, requiredPerms = []) {
+		this.attribute_name = attrName;
+		this.required_permissions = requiredPerms;
+	}
+}
+
+module.exports = PermissionAttributeResponseObject;