@dereekb/firebase-server 13.0.7 → 13.2.0

package/index.cjs.js

@@ -7,6 +7,7 @@ var date = require('@dereekb/date');
 var makeError = require('make-error');
 var rxjs = require('rxjs');
 var firestore = require('@google-cloud/firestore');
+var crypto = require('crypto');
 var common = require('@nestjs/common');
 var nestjs = require('@dereekb/nestjs');
 var v2 = require('firebase-functions/v2');
@@ -1048,6 +1049,140 @@ function googleCloudFirestoreDrivers() {
  */
 const googleCloudFirestoreContextFactory = firebase.firestoreContextFactory(googleCloudFirestoreDrivers());
 
+// MARK: Encrypted Field
+/**
+ * AES-256-GCM encryption constants.
+ */
+const ENCRYPTED_FIELD_ALGORITHM = 'aes-256-gcm';
+const ENCRYPTED_FIELD_IV_LENGTH = 12;
+const ENCRYPTED_FIELD_AUTH_TAG_LENGTH = 16;
+const ENCRYPTED_FIELD_KEY_LENGTH = 32;
+/**
+ * Resolves the encryption key Buffer from a secret source.
+ *
+ * @param source - The secret source configuration.
+ * @returns A 32-byte Buffer for AES-256 encryption.
+ * @throws Error if the resolved key is not 64 hex characters.
+ */
+function resolveEncryptionKey(source) {
+    let hex;
+    if (typeof source === 'string') {
+        hex = source;
+    }
+    else if (typeof source === 'function') {
+        hex = source();
+    }
+    else {
+        const envValue = process.env[source.env];
+        if (!envValue) {
+            throw new Error(`firestoreEncryptedField: environment variable "${source.env}" is not set.`);
+        }
+        hex = envValue;
+    }
+    if (hex.length !== ENCRYPTED_FIELD_KEY_LENGTH * 2) {
+        throw new Error(`firestoreEncryptedField: expected a ${ENCRYPTED_FIELD_KEY_LENGTH * 2}-character hex key, got ${hex.length} characters.`);
+    }
+    return Buffer.from(hex, 'hex');
+}
+/**
+ * Encrypts a JSON-serializable value to a base64-encoded string.
+ *
+ * Format: base64(IV (12 bytes) + ciphertext + authTag (16 bytes))
+ *
+ * @param value - The value to encrypt.
+ * @param key - The 32-byte encryption key.
+ * @returns The encrypted value as a base64 string.
+ */
+function encryptValue(value, key) {
+    const iv = crypto.randomBytes(ENCRYPTED_FIELD_IV_LENGTH);
+    const cipher = crypto.createCipheriv(ENCRYPTED_FIELD_ALGORITHM, key, iv);
+    const plaintext = JSON.stringify(value);
+    const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+    const combined = Buffer.concat([iv, encrypted, authTag]);
+    return combined.toString('base64');
+}
+/**
+ * Decrypts a base64-encoded string back to the original value.
+ *
+ * @param encoded - The base64-encoded encrypted string (IV + ciphertext + authTag).
+ * @param key - The 32-byte encryption key.
+ * @returns The decrypted value.
+ */
+function decryptValue(encoded, key) {
+    const combined = Buffer.from(encoded, 'base64');
+    const iv = combined.subarray(0, ENCRYPTED_FIELD_IV_LENGTH);
+    const authTag = combined.subarray(combined.length - ENCRYPTED_FIELD_AUTH_TAG_LENGTH);
+    const ciphertext = combined.subarray(ENCRYPTED_FIELD_IV_LENGTH, combined.length - ENCRYPTED_FIELD_AUTH_TAG_LENGTH);
+    const decipher = crypto.createDecipheriv(ENCRYPTED_FIELD_ALGORITHM, key, iv);
+    decipher.setAuthTag(authTag);
+    const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    return JSON.parse(decrypted.toString('utf8'));
+}
+/**
+ * Creates a Firestore field mapping that encrypts/decrypts a JSON-serializable value
+ * using AES-256-GCM. The value is stored in Firestore as a base64-encoded string.
+ *
+ * The encryption key is resolved from the configured secret source on each read/write,
+ * allowing for key rotation via environment variable changes.
+ *
+ * @example
+ * ```typescript
+ * const jwksField = firestoreEncryptedField<JWKSet>({
+ *   secret: { env: 'FIRESTORE_ENCRYPTION_KEY' },
+ *   default: () => ({ keys: [] })
+ * });
+ * ```
+ *
+ * @template T - The JSON-serializable value type.
+ * @param config - Encryption field configuration.
+ * @returns A field mapping configuration for encrypted values.
+ */
+function firestoreEncryptedField(config) {
+    const { secret, default: defaultValue } = config;
+    return firebase.firestoreField({
+        default: defaultValue,
+        fromData: (data) => {
+            const key = resolveEncryptionKey(secret);
+            return decryptValue(data, key);
+        },
+        toData: (value) => {
+            const key = resolveEncryptionKey(secret);
+            return encryptValue(value, key);
+        }
+    });
+}
+/**
+ * Creates a Firestore field mapping for an optional encrypted field.
+ *
+ * When the value is null/undefined, it is stored/read as null. When present, it is
+ * encrypted/decrypted using AES-256-GCM.
+ *
+ * @example
+ * ```typescript
+ * const optionalSecretField = optionalFirestoreEncryptedField<OAuthClientSecret>({
+ *   secret: { env: 'FIRESTORE_ENCRYPTION_KEY' }
+ * });
+ * ```
+ *
+ * @template T - The JSON-serializable value type.
+ * @param config - Encryption field configuration.
+ * @returns A field mapping configuration for optional encrypted values.
+ */
+function optionalFirestoreEncryptedField(config) {
+    const { secret } = config;
+    return firebase.optionalFirestoreField({
+        transformFromData: (data) => {
+            const key = resolveEncryptionKey(secret);
+            return decryptValue(data, key);
+        },
+        transformToData: (value) => {
+            const key = resolveEncryptionKey(secret);
+            return encryptValue(value, key);
+        }
+    });
+}
+
 function assertContextHasAuth(context) {
     if (!isContextWithAuthData(context)) {
         throw unauthenticatedContextHasNoUidError();
@@ -1153,10 +1288,6 @@ function __param(paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 }
 
-function __metadata(metadataKey, metadataValue) {
-    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(metadataKey, metadataValue);
-}
-
 typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
     var e = new Error(message);
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
@@ -1734,43 +1865,34 @@ function firebaseServerActionsTransformContext(options) {
 }
 const FIREBASE_SERVER_VALIDATION_ERROR_CODE = 'VALIDATION_ERROR';
 /**
- *
- * @param validationError
- * @returns
+ * Creates a server error object from ArkType validation errors.
  */
-function firebaseServerValidationServerError(validationError) {
-    const nestValidationExceptionFactory = new common.ValidationPipe({
-        forbidUnknownValues: false
-    }).createExceptionFactory();
-    const nestError = nestValidationExceptionFactory(validationError);
-    const data = nestError.getResponse();
+function firebaseServerValidationServerError(validationErrors) {
     return {
         message: 'One or more data/form validation errors occurred.',
         code: FIREBASE_SERVER_VALIDATION_ERROR_CODE,
-        data
+        data: {
+            message: validationErrors.summary
+        }
     };
 }
 /**
  * Creates a new badRequestError with the validation error details as the response data.
- *
- * @param validationError
- * @returns
  */
-function firebaseServerValidationError(validationError) {
-    const serverError = firebaseServerValidationServerError(validationError);
+function firebaseServerValidationError(validationErrors) {
+    const serverError = firebaseServerValidationServerError(validationErrors);
     return badRequestError(serverError);
 }
 function firebaseServerActionsTransformFactory(options) {
-    const { logError, defaultValidationOptions } = options ?? {};
+    const { logError } = options ?? {};
     const logErrorFunction = logError !== false ? (typeof logError === 'function' ? logError : defaultFirebaseServerActionsTransformFactoryLogErrorFunction) : util.mapIdentityFunction;
     return model.transformAndValidateObjectFactory({
-        handleValidationError: (validationError) => {
-            const serverError = firebaseServerValidationServerError(validationError);
+        handleValidationError: async (validationErrors) => {
+            const serverError = firebaseServerValidationServerError(validationErrors);
             const { data } = serverError;
             logErrorFunction(data);
             throw badRequestError(serverError);
-        },
-        defaultValidationOptions
+        }
     });
 }
 
@@ -1829,8 +1951,7 @@ exports.FirebaseAppCheckMiddleware = class FirebaseAppCheckMiddleware {
 exports.FirebaseAppCheckMiddleware = __decorate([
     common.Injectable(),
     __param(0, common.Optional()),
-    __param(0, common.Inject(GlobalRoutePrefixConfig)),
-    __metadata("design:paramtypes", [Object])
+    __param(0, common.Inject(GlobalRoutePrefixConfig))
 ], exports.FirebaseAppCheckMiddleware);
 /**
  * Verifies the AppCheck parameter. If it fails, a value is returned.
@@ -2780,6 +2901,7 @@ exports.firebaseServerStorageModuleMetadata = firebaseServerStorageModuleMetadat
 exports.firebaseServerValidationError = firebaseServerValidationError;
 exports.firebaseServerValidationServerError = firebaseServerValidationServerError;
 exports.firestoreClientQueryConstraintFunctionsDriver = firestoreClientQueryConstraintFunctionsDriver;
+exports.firestoreEncryptedField = firestoreEncryptedField;
 exports.firestoreServerIncrementUpdateToUpdateData = firestoreServerIncrementUpdateToUpdateData;
 exports.forbiddenError = forbiddenError;
 exports.getAuthUserOrUndefined = getAuthUserOrUndefined;
@@ -2836,6 +2958,7 @@ exports.onCallUpdateModel = onCallUpdateModel;
 exports.onScheduleHandlerWithNestApplicationFactory = onScheduleHandlerWithNestApplicationFactory;
 exports.onScheduleHandlerWithNestContextFactory = onScheduleHandlerWithNestContextFactory;
 exports.optionalAuthContext = optionalAuthContext;
+exports.optionalFirestoreEncryptedField = optionalFirestoreEncryptedField;
 exports.permissionDeniedError = permissionDeniedError;
 exports.phoneNumberAlreadyExistsError = phoneNumberAlreadyExistsError;
 exports.preconditionConflictError = preconditionConflictError;