@dereekb/firebase-server 13.1.0 → 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();
@@ -2766,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;
@@ -2822,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;