@mohasinac/appkit 4.29.1 → 4.30.1

package/dist/providers/db-firebase/sieve.js

@@ -76,12 +76,24 @@ import { createFirebaseAdapter } from "@mohasinac/sievejs/adapters/firebase";
  * (OR semantics). The stock adapter tries `whereOr` which Firestore Admin SDK
  * doesn't support. Firestore's `.where(field, "in", [v1, v2])` is the correct
  * equivalent and supports up to 30 values.
+ *
+ * It also REPORTS every case-insensitive condition it sees, because those are
+ * the ones the stock adapter throws on — see `buildFilteredSieveQuery`.
+ * Reading `operatorIsCaseInsensitive` off the parsed condition is deliberate:
+ * re-scanning the raw filter string for a trailing `*` cannot tell an operator
+ * suffix from a `*` inside a value (`title==foo*bar`).
  */
-function createEnhancedFirebaseAdapter() {
+function createEnhancedFirebaseAdapter(onCaseInsensitive) {
     const base = createFirebaseAdapter();
     return {
         ...base,
         applyFilterGroup(query, group) {
+            if (onCaseInsensitive) {
+                for (const c of group) {
+                    if (c.operatorIsCaseInsensitive)
+                        onCaseInsensitive(c);
+                }
+            }
             if (group.length > 1 &&
                 group.every((c) => c.parsedOperator === "equals" &&
                     !c.operatorIsNegated &&
@@ -94,6 +106,9 @@ function createEnhancedFirebaseAdapter() {
     };
 }
 import { FirebaseRepository } from "./base";
+// Defining module, not the barrel — `errors/index` re-exports a lot, and this
+// file is imported by every repository (Root Cause #18).
+import { ValidationError } from "../../errors/validation-error";
 import { deserializeTimestamps, getFirestoreCount } from "./helpers";
 import { expandFilterAliases as _expandFilterAliases, } from "./filter-aliases";
 // Re-export the pure alias helper + types so consumers that already imported
@@ -138,6 +153,22 @@ function withAliasesExpanded(model, aliases) {
  */
 function buildFilteredSieveQuery(baseQuery, model, fields, merged, aliases) {
     const effective = withAliasesExpanded(model, aliases);
+    // Case-insensitive operators (`@=*`, `_=*`, `==*`, `!=*`, `_-=*`) are the one
+    // shape the Firebase adapter throws on, and `throwExceptions: false` turns
+    // that throw into SILENCE — measured, not assumed:
+    //
+    //   filters="status==published,title==foo"      → where, where, orderBy   ✅
+    //   filters="title@=*dranzer,status==published" → NOTHING APPLIED         ✗
+    //   filters="status==published,title@=*dranzer" → where(status) only, no sort
+    //
+    // The processor catches the adapter's throw and returns the query as of that
+    // point, so the remaining clauses AND the entire sort phase are discarded.
+    // With the CI clause first that is the bare collection — every facet the user
+    // picked, gone, and a 200 carrying the whole table as "search results".
+    // `ignoreUnsupported: true` does NOT help; it drops the clause just as
+    // quietly. So the only honest options are "throw" or "keep lying", and a
+    // caller asking for an operator this backend cannot express is a 400.
+    const caseInsensitive = [];
     const processor = new SieveProcessorBase({
         // MUST be the enhanced adapter, not the stock one. This is the path
         // `BaseRepository.sieveQuery` delegates to, so it is what ProductRepository
@@ -148,14 +179,25 @@ function buildFilteredSieveQuery(baseQuery, model, fields, merged, aliases) {
         // not implement; `throwExceptions: false` then swallowed it and the clause
         // vanished, returning the ENTIRE collection instead of the selected subset.
         // See __tests__/sieve-or-group.test.ts.
-        adapter: createEnhancedFirebaseAdapter(),
+        adapter: createEnhancedFirebaseAdapter((c) => caseInsensitive.push(c)),
         autoLoadConfig: false,
         options: merged,
         fields,
     });
-    return processor.apply(effective, baseQuery, {
+    const query = processor.apply(effective, baseQuery, {
         applyPagination: false,
     });
+    // Thrown AFTER apply so the message can name every offending clause, not just
+    // the first one the adapter happened to reach.
+    if (caseInsensitive.length > 0) {
+        const clauses = caseInsensitive
+            .map((c) => `${c.field} (${c.parsedOperator})`)
+            .join(", ");
+        throw new ValidationError(`Case-insensitive filter operators are not supported by Firestore. ` +
+            `Offending clause(s): ${clauses}. Use searchTxt token search instead ` +
+            `— see appkit/src/utils/search-txt.ts.`, { fields: caseInsensitive.map((c) => c.field) });
+    }
+    return query;
 }
 /**
  * Count matching documents WITHOUT reading any of them.
@@ -189,7 +231,9 @@ export async function applySieveToFirestore(params) {
     // the full Sieve DSL from the base.
     const pagedQ = filteredQ.offset((page - 1) * pageSize).limit(pageSize);
     const snap = await pagedQ.get();
-    const items = snap.docs.map((d) => deserializeTimestamps({ id: d.id, ...d.data() }));
+    const items = snap.docs.map((d) => params.mapDoc
+        ? params.mapDoc(d)
+        : deserializeTimestamps({ id: d.id, ...d.data() }));
     const totalPages = total === 0 ? 0 : Math.max(1, Math.ceil(total / pageSize));
     return {
         items,

package/dist/security/browser.d.ts

@@ -2,6 +2,6 @@ export { generateNonce, buildCSP } from "./csp";
 export { requireAuth, requireRole, requireOwnership, requireEmailVerified, requireActiveAccount, canChangeRole, getRoleLevel, } from "./authorization";
 export type { UserRole } from "./authorization";
 export { redactPii } from "./pii-redact";
-export { USER_PII_FIELDS, USER_PII_INDEX_MAP, ADDRESS_PII_FIELDS, ORDER_PII_FIELDS, PAYOUT_PII_FIELDS, PAYOUT_PII_INDEX_MAP, BID_PII_FIELDS, NEWSLETTER_PII_FIELDS, NEWSLETTER_PII_INDEX_MAP, TOKEN_PII_FIELDS, TOKEN_PII_INDEX_MAP, REVIEW_PII_FIELDS, REVIEW_PII_INDEX_MAP, OFFER_PII_FIELDS, CHAT_PII_FIELDS, EVENT_ENTRY_PII_FIELDS, } from "./pii-schemas";
+export { USER_PII_FIELDS, USER_PII_INDEX_MAP, ADDRESS_PII_FIELDS, ORDER_PII_FIELDS, PAYOUT_PII_FIELDS, PAYOUT_PII_INDEX_MAP, BID_PII_FIELDS, TOKEN_PII_FIELDS, TOKEN_PII_INDEX_MAP, REVIEW_PII_FIELDS, REVIEW_PII_INDEX_MAP, OFFER_PII_FIELDS, CHAT_PII_FIELDS, EVENT_ENTRY_PII_FIELDS, } from "./pii-schemas";
 export type { Permission, RoleDefinition, RbacConfig, ResolvedUser, RbacHookReturn, } from "./rbac";
 export { DEFAULT_ROLES, resolvePermissions, hasPermission, hasAllPermissions, hasAnyPermission, createRbacHook, Can, createRbacMiddleware, } from "./rbac";

package/dist/security/browser.js

@@ -1,5 +1,5 @@
 export { generateNonce, buildCSP } from "./csp";
 export { requireAuth, requireRole, requireOwnership, requireEmailVerified, requireActiveAccount, canChangeRole, getRoleLevel, } from "./authorization";
 export { redactPii } from "./pii-redact";
-export { USER_PII_FIELDS, USER_PII_INDEX_MAP, ADDRESS_PII_FIELDS, ORDER_PII_FIELDS, PAYOUT_PII_FIELDS, PAYOUT_PII_INDEX_MAP, BID_PII_FIELDS, NEWSLETTER_PII_FIELDS, NEWSLETTER_PII_INDEX_MAP, TOKEN_PII_FIELDS, TOKEN_PII_INDEX_MAP, REVIEW_PII_FIELDS, REVIEW_PII_INDEX_MAP, OFFER_PII_FIELDS, CHAT_PII_FIELDS, EVENT_ENTRY_PII_FIELDS, } from "./pii-schemas";
+export { USER_PII_FIELDS, USER_PII_INDEX_MAP, ADDRESS_PII_FIELDS, ORDER_PII_FIELDS, PAYOUT_PII_FIELDS, PAYOUT_PII_INDEX_MAP, BID_PII_FIELDS, TOKEN_PII_FIELDS, TOKEN_PII_INDEX_MAP, REVIEW_PII_FIELDS, REVIEW_PII_INDEX_MAP, OFFER_PII_FIELDS, CHAT_PII_FIELDS, EVENT_ENTRY_PII_FIELDS, } from "./pii-schemas";
 export { DEFAULT_ROLES, resolvePermissions, hasPermission, hasAllPermissions, hasAnyPermission, createRbacHook, Can, createRbacMiddleware, } from "./rbac";

package/dist/security/index.d.ts

@@ -4,9 +4,9 @@ export type { RateLimitConfig, RateLimitResult } from "./rate-limit";
 export { requireAuth, requireRole, requireOwnership, requireEmailVerified, requireActiveAccount, canChangeRole, getRoleLevel, } from "./authorization";
 export type { UserRole } from "./authorization";
 export { redactPii, safeDisplayName, safeDisplayEmail, maskIp } from "./pii-redact";
-export { encryptValue, decryptValue, hmacBlindIndex, encryptPiiFields, decryptPiiFields, encryptPii, decryptPii, piiBlindIndex, addPiiIndices, piiIndicesFor, getPiiConfigError, encryptShippingAddress, decryptShippingAddress, encryptPayoutDetails, decryptPayoutDetails, encryptShippingConfig, decryptShippingConfig, encryptPayoutBankAccount, decryptPayoutBankAccount, } from "./pii-encrypt";
+export { encryptValue, decryptValue, hmacBlindIndex, encryptPiiFields, decryptPiiFields, encryptPii, decryptPii, piiBlindIndex, piiIndicesFor, getPiiConfigError, encryptShippingAddress, decryptShippingAddress, encryptPayoutDetails, decryptPayoutDetails, encryptShippingConfig, decryptShippingConfig, encryptPayoutBankAccount, decryptPayoutBankAccount, } from "./pii-encrypt";
 export { isPiiEncrypted, maskName, maskEmail, maskPublicReview, maskPublicBid, maskPublicEventEntry, maskOfferForSeller, ENC_PREFIX, HMAC_PREFIX, } from "./pii-mask";
-export { USER_PII_FIELDS, USER_PII_INDEX_MAP, ADDRESS_PII_FIELDS, ORDER_PII_FIELDS, PAYOUT_PII_FIELDS, PAYOUT_PII_INDEX_MAP, BID_PII_FIELDS, NEWSLETTER_PII_FIELDS, NEWSLETTER_PII_INDEX_MAP, TOKEN_PII_FIELDS, TOKEN_PII_INDEX_MAP, REVIEW_PII_FIELDS, REVIEW_PII_INDEX_MAP, OFFER_PII_FIELDS, CHAT_PII_FIELDS, EVENT_ENTRY_PII_FIELDS, LOTTERY_ENTRY_PII_FIELDS, PAYMENT_METHOD_PII_FIELDS, } from "./pii-schemas";
+export { USER_PII_FIELDS, USER_PII_INDEX_MAP, ADDRESS_PII_FIELDS, ORDER_PII_FIELDS, PAYOUT_PII_FIELDS, PAYOUT_PII_INDEX_MAP, BID_PII_FIELDS, TOKEN_PII_FIELDS, TOKEN_PII_INDEX_MAP, REVIEW_PII_FIELDS, REVIEW_PII_INDEX_MAP, OFFER_PII_FIELDS, CHAT_PII_FIELDS, EVENT_ENTRY_PII_FIELDS, LOTTERY_ENTRY_PII_FIELDS, PAYMENT_METHOD_PII_FIELDS, } from "./pii-schemas";
 export { encryptSecret, decryptSecret, isSecretEncrypted, maskSecret, } from "./settings-encryption";
 export type { Permission, RoleDefinition, RbacConfig, ResolvedUser, RbacHookReturn, } from "./rbac";
 export { DEFAULT_ROLES, resolvePermissions, hasPermission, hasAllPermissions, hasAnyPermission, createRbacHook, Can, createRequirePermission, createRequirePermissionSync, createRbacMiddleware, } from "./rbac";

package/dist/security/index.js

@@ -2,11 +2,11 @@ export { generateNonce, buildCSP } from "./csp";
 export { rateLimit, applyRateLimit, rateLimitByIdentifier, RateLimitPresets, clearRateLimitStore, getClientIP, hashGuestIdentity, } from "./rate-limit";
 export { requireAuth, requireRole, requireOwnership, requireEmailVerified, requireActiveAccount, canChangeRole, getRoleLevel, } from "./authorization";
 export { redactPii, safeDisplayName, safeDisplayEmail, maskIp } from "./pii-redact";
-export { encryptValue, decryptValue, hmacBlindIndex, encryptPiiFields, decryptPiiFields, encryptPii, decryptPii, piiBlindIndex, addPiiIndices, piiIndicesFor, getPiiConfigError, encryptShippingAddress, decryptShippingAddress, encryptPayoutDetails, decryptPayoutDetails, encryptShippingConfig, decryptShippingConfig, encryptPayoutBankAccount, decryptPayoutBankAccount, } from "./pii-encrypt";
+export { encryptValue, decryptValue, hmacBlindIndex, encryptPiiFields, decryptPiiFields, encryptPii, decryptPii, piiBlindIndex, piiIndicesFor, getPiiConfigError, encryptShippingAddress, decryptShippingAddress, encryptPayoutDetails, decryptPayoutDetails, encryptShippingConfig, decryptShippingConfig, encryptPayoutBankAccount, decryptPayoutBankAccount, } from "./pii-encrypt";
 // Crypto-free display-masking helpers -- sourced from pii-mask.ts (not
 // pii-encrypt.ts) so this barrel stays safe to re-export from the
 // universal client+server index.ts. See pii-mask.ts's header comment.
 export { isPiiEncrypted, maskName, maskEmail, maskPublicReview, maskPublicBid, maskPublicEventEntry, maskOfferForSeller, ENC_PREFIX, HMAC_PREFIX, } from "./pii-mask";
-export { USER_PII_FIELDS, USER_PII_INDEX_MAP, ADDRESS_PII_FIELDS, ORDER_PII_FIELDS, PAYOUT_PII_FIELDS, PAYOUT_PII_INDEX_MAP, BID_PII_FIELDS, NEWSLETTER_PII_FIELDS, NEWSLETTER_PII_INDEX_MAP, TOKEN_PII_FIELDS, TOKEN_PII_INDEX_MAP, REVIEW_PII_FIELDS, REVIEW_PII_INDEX_MAP, OFFER_PII_FIELDS, CHAT_PII_FIELDS, EVENT_ENTRY_PII_FIELDS, LOTTERY_ENTRY_PII_FIELDS, PAYMENT_METHOD_PII_FIELDS, } from "./pii-schemas";
+export { USER_PII_FIELDS, USER_PII_INDEX_MAP, ADDRESS_PII_FIELDS, ORDER_PII_FIELDS, PAYOUT_PII_FIELDS, PAYOUT_PII_INDEX_MAP, BID_PII_FIELDS, TOKEN_PII_FIELDS, TOKEN_PII_INDEX_MAP, REVIEW_PII_FIELDS, REVIEW_PII_INDEX_MAP, OFFER_PII_FIELDS, CHAT_PII_FIELDS, EVENT_ENTRY_PII_FIELDS, LOTTERY_ENTRY_PII_FIELDS, PAYMENT_METHOD_PII_FIELDS, } from "./pii-schemas";
 export { encryptSecret, decryptSecret, isSecretEncrypted, maskSecret, } from "./settings-encryption";
 export { DEFAULT_ROLES, resolvePermissions, hasPermission, hasAllPermissions, hasAnyPermission, createRbacHook, Can, createRequirePermission, createRequirePermissionSync, createRbacMiddleware, } from "./rbac";

package/dist/security/pii-encrypt.d.ts

@@ -22,10 +22,6 @@ export declare function decryptValue(ciphertext: string): string;
  */
 export declare function hmacBlindIndex(value: string): string;
 export declare function encryptPiiFields<T extends object>(doc: T, piiFields: string[]): T;
-/**
- * Decrypt specified PII fields in a Firestore document.
- * Fields that are not encrypted (no `enc:v1:` prefix) are passed through.
- */
 export declare function decryptPiiFields<T extends object>(doc: T, piiFields: string[]): T;
 /** Alias for encryptValue — encrypts a PII plaintext string. */
 export declare function encryptPii(plaintext: string | null | undefined): string | null | undefined;
@@ -42,16 +38,22 @@ export declare function piiBlindIndex(plaintext: string): string;
  * Blind-index fields ONLY — derived from `source` (which must be plaintext),
  * with none of `source`'s own keys carried along.
  *
- * Use this, never `addPiiIndices`, when merging indices onto an already-encrypted
- * object. `addPiiIndices` returns `{...source, ...indices}`, so spreading its
- * result over ciphertext silently restores the plaintext — which is exactly how
- * `payouts.sellerEmail`, `payouts.upiId` and `reviews.userName` ended up stored
- * in cleartext beside a valid index.
+ * This is the ONLY index helper. Its predecessor, `addPiiIndices`, returned
+ * `{...source, ...indices}`, so spreading its result over ciphertext silently
+ * restored the plaintext — which is how `payouts.sellerEmail`, `payouts.upiId`
+ * and `reviews.userName` ended up stored in cleartext beside a valid index, and
+ * how both token repositories wrote every verification and password-reset email
+ * in cleartext until it was deleted. Returning indices only makes that class of
+ * bug unrepresentable rather than merely documented.
+ *
+ * Merge order is still the caller's responsibility:
+ *   `{ ...encryptPiiFields(data, FIELDS), ...piiIndicesFor(data, MAP) }`
+ * — both arguments read the PLAINTEXT `data`; hashing ciphertext yields an
+ * index nothing can look up.
  *
  * @param source plaintext document — hashing ciphertext produces a useless index
  */
 export declare function piiIndicesFor(source: object, mapping: Record<string, string>): Record<string, string>;
-export declare function addPiiIndices<T extends object>(obj: T, mapping: Record<string, string>): T;
 /**
  * Encrypt PII inside a shipping address stored in an order.
  * Supports string and object address shapes.

package/dist/security/pii-encrypt.js

@@ -9,7 +9,9 @@
  * Ciphertext format: "enc:v1:<iv_b64>:<ciphertext_b64>:<authtag_b64>"
  * Blind index format: "hmac-sha256:<sha256_hex>"
  */
-import { ENC_PREFIX, HMAC_PREFIX, isPiiEncrypted } from "./pii-mask";
+import { ENC_PREFIX, HMAC_PREFIX, isPiiEncrypted, encEnvelopeKind } from "./pii-mask";
+import { serverLogger } from "../monitoring/server-logger";
+import { normalizeError } from "../errors/normalize";
 // Re-exported for backward-compat with existing direct imports of these
 // symbols from this file — the actual crypto-free definitions live in
 // pii-mask.ts (see that file's header comment for why the split exists).
@@ -50,10 +52,32 @@ function getEncKey() {
     const hex = normalizePiiSecretValue(process.env.PII_ENCRYPTION_KEY);
     return Buffer.from(hex, "hex");
 }
+/**
+ * Blind-index key. Normalised and validated exactly like `getEncKey`.
+ *
+ * It previously read the env var RAW while `getEncKey` normalised the same
+ * value — so the two keys were derived from one variable by two different code
+ * paths. `Buffer.from(x, "hex")` does not throw on bad input; it truncates
+ * silently at the first non-hex byte. A BOM or trailing CR (a problem this repo
+ * has hit before — see scripts/_fix-vercel-env-bom.mjs) would therefore give
+ * the encryptor a 32-byte key and the indexer a 0-byte one, and every blind
+ * index written from that moment would be unmatchable against the existing
+ * ones. `findByEmail` would simply stop finding people — indistinguishable
+ * from "no such user", with nothing logged.
+ *
+ * Verified before changing: on the current environment the raw and normalised
+ * reads produce byte-identical keys, so this is a no-op for every index
+ * already in Firestore.
+ */
 function getHmacKey() {
-    const raw = process.env["PII_HMAC_KEY"] ?? process.env["PII_ENCRYPTION_KEY"] ?? "";
+    const raw = normalizePiiSecretValue(process.env["PII_HMAC_KEY"] ?? process.env["PII_ENCRYPTION_KEY"] ?? "");
     if (!raw)
         throw new Error("PII_HMAC_KEY env var is not set — cannot generate blind PII index");
+    if (!/^[0-9a-fA-F]{64}$/.test(raw))
+        // Fail loudly at the boundary. A startup error is recoverable; a silently
+        // truncated key is not.
+        throw new Error("PII_HMAC_KEY (or its PII_ENCRYPTION_KEY fallback) must be a 64-character hex string — " +
+            `got ${raw.length} chars. Buffer.from would truncate this silently and desync every blind index.`);
     return Buffer.from(raw, "hex");
 }
 /** Encrypt a plaintext string with AES-256-GCM. */
@@ -70,10 +94,19 @@ export function encryptValue(plaintext) {
 export function decryptValue(ciphertext) {
     if (!ciphertext.startsWith(ENC_PREFIX))
         return ciphertext;
+    // Name the actual problem. A settings-encrypted value shares this prefix but
+    // uses dot separators and a different key; it used to fail here as a bare
+    // part-count error, which reads like corruption rather than "wrong system".
+    if (encEnvelopeKind(ciphertext) === "settings") {
+        throw new Error("Value is settings-encrypted (SETTINGS_ENCRYPTION_KEY, dot-separated), not PII-encrypted — decryptValue cannot read it");
+    }
     const inner = ciphertext.slice(ENC_PREFIX.length);
     const parts = inner.split(":");
     if (parts.length !== 3)
-        throw new Error(`Invalid PII ciphertext: ${ciphertext}`);
+        // NEVER interpolate the value. This used to embed the whole ciphertext,
+        // which then flowed into DatabaseError and serverLogger.error — encrypted
+        // PII sitting in the logs on every malformed row. Shape only.
+        throw new Error(`Invalid PII ciphertext: expected 3 colon-separated parts after ${ENC_PREFIX}, got ${parts.length} (${ciphertext.length} chars)`);
     const [ivB64, encB64, tagB64] = parts;
     const { createDecipheriv } = nodeCrypto();
     const key = getEncKey();
@@ -124,14 +157,20 @@ function setPath(obj, path, value) {
 /**
  * Encrypt the named fields, adding a blind index alongside each top-level one.
  *
- * Supports dotted paths (`deviceInfo.ip`, `whatsappConfig.accessToken`). This
- * was a flat top-level loop that skipped anything non-string, which is why
- * nested PII stayed in plaintext — and why the exported
- * `STORE_SECRET_FIELDS = ["whatsappConfig.accessToken"]` was unusable by the
- * very function it was written for.
+ * Supports dotted paths (`deviceInfo.ip`, `location.city`). This was a flat
+ * top-level loop that skipped anything non-string, which is why nested PII
+ * stayed in plaintext.
+ *
+ * 🛑 That dotted-path support is also what made it possible to point this
+ * function at a field belonging to the OTHER crypto system. A store's
+ * `whatsappConfig.accessToken` is encrypted with SETTINGS_ENCRYPTION_KEY;
+ * passing it here would encrypt it with the PII key while
+ * `StoreRepository.decryptSecrets` kept decrypting with the settings one.
+ * Only ever pass fields from this file's own `*_PII_FIELDS` lists.
  *
- * Idempotent: a value already carrying `enc:v1:` is left alone, so re-running
- * over a partially-migrated document is safe.
+ * Idempotent: a value already carrying `enc:v1:` is left alone — whichever
+ * system wrote it — so re-running over a partially-migrated document is safe
+ * and a settings-encrypted value is never double-wrapped.
  */
 /**
  * Encrypt `itemPath` on every element of the array at `arrayPath`.
@@ -192,6 +231,33 @@ export function encryptPiiFields(doc, piiFields) {
  * Decrypt specified PII fields in a Firestore document.
  * Fields that are not encrypted (no `enc:v1:` prefix) are passed through.
  */
+/**
+ * Decrypt one value, or return a sentinel and warn.
+ *
+ * A single corrupt or foreign-format row must not take out the page. Before
+ * the sieve read path started calling `mapDoc` (which is what decrypts),
+ * a bad value was merely rendered as ciphertext — cosmetic. Once decryption
+ * actually runs on list reads, an unguarded throw inside a 100-row admin page
+ * turns that cosmetic defect into a 500 for the whole list.
+ *
+ * Same fail-soft posture `SiteSettingsRepository.getDecryptedCredentials`
+ * already takes for the settings key.
+ *
+ * The warning names the FIELD, never the value.
+ */
+function decryptOrWarn(value, field) {
+    try {
+        return decryptValue(value);
+    }
+    catch (err) {
+        const normalized = normalizeError(err);
+        serverLogger.warn("PII decrypt failed — field left empty", {
+            field,
+            reason: normalized.message,
+        });
+        return "";
+    }
+}
 export function decryptPiiFields(doc, piiFields) {
     const result = { ...doc };
     for (const field of piiFields) {
@@ -211,7 +277,7 @@ export function decryptPiiFields(doc, piiFields) {
                 const clone = { ...el };
                 const value = itemPath ? getPath(clone, itemPath) : undefined;
                 if (typeof value === "string" && value.startsWith(ENC_PREFIX)) {
-                    setPath(clone, itemPath, decryptValue(value));
+                    setPath(clone, itemPath, decryptOrWarn(value, field));
                 }
                 return clone;
             }));
@@ -220,13 +286,13 @@ export function decryptPiiFields(doc, piiFields) {
         if (field.includes(".")) {
             const value = getPath(result, field);
             if (typeof value === "string" && value.startsWith(ENC_PREFIX)) {
-                setPath(result, field, decryptValue(value));
+                setPath(result, field, decryptOrWarn(value, field));
             }
             continue;
         }
         const value = result[field];
         if (typeof value === "string" && value.startsWith(ENC_PREFIX)) {
-            result[field] = decryptValue(value);
+            result[field] = decryptOrWarn(value, field);
         }
     }
     return result;
@@ -259,11 +325,18 @@ export function piiBlindIndex(plaintext) {
  * Blind-index fields ONLY — derived from `source` (which must be plaintext),
  * with none of `source`'s own keys carried along.
  *
- * Use this, never `addPiiIndices`, when merging indices onto an already-encrypted
- * object. `addPiiIndices` returns `{...source, ...indices}`, so spreading its
- * result over ciphertext silently restores the plaintext — which is exactly how
- * `payouts.sellerEmail`, `payouts.upiId` and `reviews.userName` ended up stored
- * in cleartext beside a valid index.
+ * This is the ONLY index helper. Its predecessor, `addPiiIndices`, returned
+ * `{...source, ...indices}`, so spreading its result over ciphertext silently
+ * restored the plaintext — which is how `payouts.sellerEmail`, `payouts.upiId`
+ * and `reviews.userName` ended up stored in cleartext beside a valid index, and
+ * how both token repositories wrote every verification and password-reset email
+ * in cleartext until it was deleted. Returning indices only makes that class of
+ * bug unrepresentable rather than merely documented.
+ *
+ * Merge order is still the caller's responsibility:
+ *   `{ ...encryptPiiFields(data, FIELDS), ...piiIndicesFor(data, MAP) }`
+ * — both arguments read the PLAINTEXT `data`; hashing ciphertext yields an
+ * index nothing can look up.
  *
  * @param source plaintext document — hashing ciphertext produces a useless index
  */
@@ -278,17 +351,6 @@ export function piiIndicesFor(source, mapping) {
     }
     return indices;
 }
-export function addPiiIndices(obj, mapping) {
-    const result = { ...obj };
-    const access = result;
-    for (const [sourceField, indexField] of Object.entries(mapping)) {
-        const val = access[sourceField];
-        if (typeof val === "string" && val) {
-            access[indexField] = piiBlindIndex(val);
-        }
-    }
-    return result;
-}
 // --- Nested-object PII helpers ----------------------------------------------
 /**
  * Encrypt PII inside a shipping address stored in an order.

package/dist/security/pii-mask.d.ts

@@ -14,7 +14,45 @@
  */
 export declare const ENC_PREFIX = "enc:v1:";
 export declare const HMAC_PREFIX = "hmac-sha256:";
-/** Check if a value is encrypted by our PII system. */
+/**
+ * Which crypto system produced an `enc:v1:` value.
+ *
+ * TWO systems share this prefix and always have:
+ *
+ *   PII      `enc:v1:` + iv `:` ciphertext `:` tag   — PII_ENCRYPTION_KEY
+ *   settings `enc:v1:` + iv `.` tag `.` ciphertext   — SETTINGS_ENCRYPTION_KEY
+ *
+ * Different separator, different field order, different key. `isPiiEncrypted`
+ * checked only the prefix and so could not tell them apart, which made every
+ * "is this ours" test wrong for one of the two — feed a settings value to
+ * `decryptValue` and it throws on the part count; feed a PII value to
+ * `decryptSecret` and it throws on a different part count. Neither error names
+ * the actual problem.
+ *
+ * Changing either prefix is NOT an option: `enc:v1:` is stamped into every
+ * encrypted value across twelve collections, and a new prefix orphans all of
+ * it. It does not need changing. Base64's alphabet is `A-Za-z0-9+/=`, which
+ * contains neither `.` nor `:` — so the two formats are ALREADY unambiguous in
+ * the data, and this function simply reads what is there. No migration.
+ */
+export type EncEnvelopeKind = "pii" | "settings" | null;
+export declare function encEnvelopeKind(value: unknown): EncEnvelopeKind;
+/**
+ * Does this value carry the `enc:v1:` prefix at all, whichever system wrote it
+ * and even if malformed?
+ *
+ * This is the check the DISPLAY masks want. `maskName`/`maskEmail` exist so
+ * ciphertext never reaches the UI, and for that purpose "settings-encrypted"
+ * and "malformed" are just as unshowable as "PII-encrypted". Narrowing them to
+ * `kind === "pii"` would let the other two render verbatim.
+ */
+export declare function hasEncPrefix(value: unknown): boolean;
+/**
+ * Check if a value is encrypted by our PII system SPECIFICALLY.
+ *
+ * Use for crypto routing — "may I hand this to decryptValue". For "is this
+ * unshowable", use `hasEncPrefix`.
+ */
 export declare function isPiiEncrypted(value: string): boolean;
 /**
  * Mask a person's name for public display.

package/dist/security/pii-mask.js

@@ -14,10 +14,39 @@
  */
 export const ENC_PREFIX = "enc:v1:";
 export const HMAC_PREFIX = "hmac-sha256:";
-/** Check if a value is encrypted by our PII system. */
-export function isPiiEncrypted(value) {
+export function encEnvelopeKind(value) {
+    if (typeof value !== "string" || !value.startsWith(ENC_PREFIX))
+        return null;
+    const inner = value.slice(ENC_PREFIX.length);
+    const colons = inner.split(":").length - 1;
+    const dots = inner.split(".").length - 1;
+    if (colons === 2 && dots === 0)
+        return "pii";
+    if (dots === 2 && colons === 0)
+        return "settings";
+    return null; // carries the prefix but neither shape — malformed
+}
+/**
+ * Does this value carry the `enc:v1:` prefix at all, whichever system wrote it
+ * and even if malformed?
+ *
+ * This is the check the DISPLAY masks want. `maskName`/`maskEmail` exist so
+ * ciphertext never reaches the UI, and for that purpose "settings-encrypted"
+ * and "malformed" are just as unshowable as "PII-encrypted". Narrowing them to
+ * `kind === "pii"` would let the other two render verbatim.
+ */
+export function hasEncPrefix(value) {
     return typeof value === "string" && value.startsWith(ENC_PREFIX);
 }
+/**
+ * Check if a value is encrypted by our PII system SPECIFICALLY.
+ *
+ * Use for crypto routing — "may I hand this to decryptValue". For "is this
+ * unshowable", use `hasEncPrefix`.
+ */
+export function isPiiEncrypted(value) {
+    return encEnvelopeKind(value) === "pii";
+}
 /**
  * Mask a person's name for public display.
  * Each word is reduced to its first letter followed by "***".
@@ -31,7 +60,7 @@ export function isPiiEncrypted(value) {
 export function maskName(name) {
     if (!name || typeof name !== "string")
         return "Anonymous";
-    if (isPiiEncrypted(name))
+    if (hasEncPrefix(name))
         return "Anonymous";
     return name
         .trim()
@@ -47,7 +76,7 @@ export function maskName(name) {
 export function maskEmail(email) {
     if (!email || typeof email !== "string")
         return "***@***.***";
-    if (isPiiEncrypted(email))
+    if (hasEncPrefix(email))
         return "***@***.***";
     const atIdx = email.indexOf("@");
     if (atIdx < 0)

package/dist/security/pii-redact.d.ts

@@ -1,16 +1,3 @@
-/**
- * PII Redaction Utility
- *
- * Recursively sanitizes objects before logging by masking or redacting
- * known PII (Personally Identifiable Information) field names.
- *
- * - Secrets (password, token, apiKey, etc.) → "[REDACTED]"
- * - Emails → partial mask: "mo***@gmail.com"
- * - Phones → last 4 digits: "***9876"
- * - Names → first char + asterisks: "J********"
- * - Addresses, financial IDs → "[REDACTED]"
- * - IPs → first octet only: "192.***.***.***"
- */
 /**
  * Mask an IPv4 address by zeroing the last three octets. Returns
  * `[REDACTED]` for IPv6 / malformed input.

package/dist/security/pii-redact.js

@@ -1,3 +1,4 @@
+import { ENC_PREFIX } from "./pii-mask";
 /**
  * PII Redaction Utility
  *
@@ -138,7 +139,8 @@ export function redactPii(data, depth = 0) {
 // ---------------------------------------------------------------------------
 // UI display helpers
 // ---------------------------------------------------------------------------
-const ENC_TOKEN_PREFIX = "enc:v1:";
+// One declaration of the prefix, shared with the crypto that produces it.
+const ENC_TOKEN_PREFIX = ENC_PREFIX;
 /**
  * Safe display name for untrusted / possibly-encrypted PII fields.
  *

package/dist/security/pii-schemas.d.ts

@@ -26,10 +26,6 @@ export declare const PAYOUT_PII_INDEX_MAP: Record<string, string>;
  * Bidder names are already masked on the public side by `maskPublicBid`.
  */
 export declare const BID_PII_FIELDS: readonly ["userEmail"];
-/** PII fields in newsletter subscribers */
-export declare const NEWSLETTER_PII_FIELDS: readonly [];
-/** Blind-index mapping for newsletter subscribers */
-export declare const NEWSLETTER_PII_INDEX_MAP: Record<string, string>;
 /**
  * PII fields in tokens (email verification / password reset).
  *
@@ -66,7 +62,5 @@ export declare const CHAT_PII_FIELDS: readonly ["buyerName", "sellerName"];
 export declare const EVENT_ENTRY_PII_FIELDS: readonly ["userDisplayName", "userEmail", "ipAddress"];
 /** PII fields in lottery entries */
 export declare const LOTTERY_ENTRY_PII_FIELDS: readonly ["userPhone", "userEmail", "userDisplayName"];
-/** Store OAuth bearer tokens — encrypted via SETTINGS_ENCRYPTION_KEY */
-export declare const STORE_SECRET_FIELDS: readonly ["whatsappConfig.accessToken"];
 /** PII fields in savedPaymentMethods — full identifier (UPI VPA, card PAN, etc.) */
 export declare const PAYMENT_METHOD_PII_FIELDS: readonly ["identifier"];

package/dist/security/pii-schemas.js

@@ -40,10 +40,19 @@ export const PAYOUT_PII_INDEX_MAP = {
  * Bidder names are already masked on the public side by `maskPublicBid`.
  */
 export const BID_PII_FIELDS = ["userEmail"];
-/** PII fields in newsletter subscribers */
-export const NEWSLETTER_PII_FIELDS = [];
-/** Blind-index mapping for newsletter subscribers */
-export const NEWSLETTER_PII_INDEX_MAP = {};
+/*
+ * NEWSLETTER_PII_FIELDS / NEWSLETTER_PII_INDEX_MAP were DELETED here.
+ *
+ * They were an empty `[]` and `{}` with no reader anywhere — only three barrel
+ * re-exports. `NewsletterRepository` does not extend `BaseRepository`; it holds
+ * its OWN module-local `NEWSLETTER_PII_FIELDS = ["email"]` and encrypts through
+ * that, so newsletter emails ARE encrypted at rest.
+ *
+ * The empty pair therefore did nothing except read, convincingly, as proof that
+ * newsletter PII was unencrypted — a shadow constant of exactly the shape in
+ * Root Cause #53, where the symbol a grep finds is not the one doing the work.
+ * Deleting it is the fix; populating it would have been a no-op.
+ */
 /**
  * PII fields in tokens (email verification / password reset).
  *
@@ -99,7 +108,21 @@ export const LOTTERY_ENTRY_PII_FIELDS = [
     "userEmail",
     "userDisplayName",
 ];
-/** Store OAuth bearer tokens — encrypted via SETTINGS_ENCRYPTION_KEY */
-export const STORE_SECRET_FIELDS = ["whatsappConfig.accessToken"];
+// `STORE_SECRET_FIELDS = ["whatsappConfig.accessToken"]` was deleted here.
+//
+// It had ZERO consumers, and its presence in this file was the whole hazard:
+// it sat in the PII-field registry, formatted identically to the entries above
+// that ARE assigned to a repository's `piiFields` — while its own doc-comment
+// said it was encrypted with SETTINGS_ENCRYPTION_KEY, the other key entirely.
+//
+// Wiring it into a `piiFields` override would have encrypted every store's Meta
+// bearer token with the PII key while `StoreRepository.decryptSecrets` kept
+// decrypting with the settings key: a hard throw on every store read, and
+// live seller tokens unrecoverable without a bespoke migration. Dotted-path
+// support was added to `encryptPiiFields` in 2026-08, which is exactly what
+// made that one-line mistake possible.
+//
+// The token is handled where it belongs — `encryptSecret`/`decryptSecret` in
+// `StoreRepository`. A constant does not need to exist for that.
 /** PII fields in savedPaymentMethods — full identifier (UPI VPA, card PAN, etc.) */
 export const PAYMENT_METHOD_PII_FIELDS = ["identifier"];