@mohasinac/appkit 4.52.4 → 4.53.0

package/dist/security/pii-accessors.js

@@ -0,0 +1,150 @@
+/**
+ * The two NAMED accessors that replace an unconditional `mapDoc` decrypt.
+ *
+ * ## Why this module exists
+ *
+ * `audit-pii-coverage`'s R3 stages fourteen repositories whose `mapDoc`
+ * decrypted PII on every read, so ciphertext never left the database and every
+ * caller silently handled plaintext. The prescription — copy
+ * `SiteSettingsRepository`: leave `mapDoc` alone and expose plaintext through a
+ * NAMED getter with a masked variant — is per-repository, and writing it
+ * fourteen times would be fourteen chances for the field→mask mapping to
+ * drift (Root Cause #75). So the rule lives here once and each repository
+ * delegates.
+ *
+ * ```ts
+ *   repo.findById(id)                  → PII fields are Encrypted<string>
+ *   repo.revealFor(doc)                → plaintext, opt-in and named
+ *   repo.maskedFor(doc)                → masked, the UI default
+ * ```
+ *
+ * ## 🛑 Masking must DECRYPT FIRST
+ *
+ * This is the trap worth stating, because getting it wrong is silent and looks
+ * like success. `maskName`/`maskEmail` in `pii-mask.ts` both begin with
+ * `if (hasEncPrefix(value)) return "Anonymous" / "***@***.***"` — a deliberate
+ * guard so ciphertext can never reach a UI. Once `mapDoc` stops decrypting,
+ * handing a stored field straight to `maskName` therefore returns "Anonymous"
+ * for EVERY row: no error, no ciphertext leak, and a masked column that is
+ * uniformly useless instead of showing "R*** K***". `maskPii` decrypts and
+ * then masks.
+ *
+ * ## Field → mask is by NAME CLASS, deliberately
+ *
+ * An email masks differently from a phone from a person's name, and the field
+ * lists these repositories already declare (`*_PII_FIELDS`) carry no type
+ * information. Classifying on the field name is the only signal available, and
+ * it is the same approach `pii-redact.ts` has always used for logs — the
+ * difference being that this module uses the USER-FACING masks from
+ * `pii-mask.ts` rather than the log-oriented ones.
+ *
+ * 🛑 The fallback is `maskName`, not "return as-is". An unrecognised PII field
+ * name must degrade toward LESS disclosure; returning the plaintext would make
+ * a new field silently public the moment someone adds it to a `*_PII_FIELDS`
+ * list without touching this file.
+ *
+ * @tag domain:security
+ * @tag layer:security
+ * @tag access:server-only
+ * @tag sideEffects:none
+ */
+import { decryptPiiFields } from "./pii-encrypt.js";
+import { maskEmail, maskName, maskPhone } from "./pii-mask.js";
+/** Dotted/`[]` path → its leaf key, which is what the name class reads. */
+function leafKey(path) {
+    const afterArray = path.includes("[]") ? path.slice(path.indexOf("[]") + 2) : path;
+    const parts = afterArray.replace(/^\./, "").split(".");
+    return parts[parts.length - 1] || path;
+}
+function maskByName(key, value) {
+    const k = leafKey(key).toLowerCase();
+    if (k.includes("email"))
+        return maskEmail(value);
+    if (k.includes("phone") || k.includes("mobile") || k.includes("contact")) {
+        return maskPhone(value);
+    }
+    // Everything else — names, addresses, UPI handles, account numbers — gets
+    // the most conservative mask available rather than passing through.
+    return maskName(value);
+}
+/**
+ * Decrypt the named PII fields. **Opt-in and named**: every call site is a
+ * deliberate decision that shows up in review and in a grep.
+ *
+ * The return type is the caller's plaintext-facing shape. That cast is the one
+ * place it is legitimate: this function performs the decryption that makes the
+ * `Encrypted<…>` brand false, which is exactly what the brand is for.
+ */
+export function revealPii(doc, piiFields) {
+    return decryptPiiFields({ ...doc }, [...piiFields]);
+}
+/**
+ * Decrypt, then mask. **The default a UI should reach for.**
+ *
+ * Returns the same shape as `revealPii` because a masked value is still a
+ * displayable string — the difference is in what it contains, which is why the
+ * two accessors must be separately named rather than one taking a boolean.
+ */
+export function maskPii(doc, piiFields) {
+    /*
+     * `FirestoreDocument`, not `Record<string, unknown>`.
+     *
+     * It is the shape this genuinely has — `decryptPiiFields` already works in
+     * `Record<string, FirestoreValue>` internally — and `unknown` here would
+     * push an `as` cast onto every leaf read below, which is what
+     * `audit-unknown-leakage` exists to stop.
+     */
+    const revealed = revealPii(doc, piiFields);
+    for (const field of piiFields) {
+        /*
+         * 🛑 DOTTED PATHS ARE MASKED, not skipped.
+         *
+         * The first draft skipped them, with a note saying a repository needing
+         * nested masking should override the method. Then `sessions` turned out to
+         * declare `deviceInfo.ip`, `deviceInfo.userAgent` and `location.city` —
+         * ALL THREE of its PII fields are nested. So the "exception" was the first
+         * real subject, and a `maskPii` returning those three DECRYPTED would be
+         * the `maskPublicBid`-returning-`{...bid}` defect exactly: a function whose
+         * name is the only evidence it masked anything (Root Cause #50).
+         *
+         * `[]` array paths are still skipped, because a per-element mask needs the
+         * array's own shape and guessing it would be the same lie one level down.
+         */
+        if (field.includes("[]"))
+            continue;
+        maskAtPath(revealed, field);
+    }
+    return revealed;
+}
+/**
+ * Mask the string at a dotted path, in place. A missing intermediate object or
+ * a non-string leaf is left alone — this walks what is there rather than
+ * creating structure to mask.
+ */
+function maskAtPath(root, path) {
+    const parts = path.split(".");
+    let node = root;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const next = node[parts[i]];
+        if (typeof next !== "object" || next === null || Array.isArray(next))
+            return;
+        // Clone on the way down: `revealPii` shallow-copies, so mutating a nested
+        // object would write through to the caller's document.
+        const copy = { ...next };
+        node[parts[i]] = copy;
+        node = copy;
+    }
+    const leaf = parts[parts.length - 1];
+    const value = node[leaf];
+    if (typeof value !== "string" || value.length === 0)
+        return;
+    node[leaf] = maskByName(leaf, value);
+}
+/** Array form of `revealPii`, for list reads. */
+export function revealPiiAll(docs, piiFields) {
+    return docs.map((d) => revealPii(d, piiFields));
+}
+/** Array form of `maskPii`, for list reads. */
+export function maskPiiAll(docs, piiFields) {
+    return docs.map((d) => maskPii(d, piiFields));
+}

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

@@ -70,11 +70,3 @@ export declare function encryptShippingConfig<T extends object>(config: T | unde
  * Decrypt PII inside seller shippingConfig.pickupAddress after reading.
  */
 export declare function decryptShippingConfig<T extends object>(config: T | undefined | null): T | undefined | null;
-/**
- * Encrypt PII on a payout bankAccount sub-object for the payouts collection.
- */
-export declare function encryptPayoutBankAccount<T extends object>(bank: T | undefined | null): T | undefined | null;
-/**
- * Decrypt PII on a payout bankAccount sub-object from the payouts collection.
- */
-export declare function decryptPayoutBankAccount<T extends object>(bank: T | undefined | null): T | undefined | null;

package/dist/security/pii-encrypt.js

@@ -428,19 +428,26 @@ export function decryptShippingConfig(config) {
     }
     return result;
 }
-/**
- * Encrypt PII on a payout bankAccount sub-object for the payouts collection.
- */
-export function encryptPayoutBankAccount(bank) {
-    if (!bank)
-        return bank;
-    return encryptPiiFields({ ...bank }, []);
-}
-/**
- * Decrypt PII on a payout bankAccount sub-object from the payouts collection.
+/*
+ * 🛑 `encryptPayoutBankAccount` / `decryptPayoutBankAccount` were DELETED
+ * 2026-10-18. Do not reintroduce them.
+ *
+ * Both were `encryptPiiFields({ ...bank }, [])` — an EMPTY field list, so a
+ * function named "encrypt" encrypted nothing and its decrypt twin undid
+ * nothing. That is R1's own defect (`EMPTY_PII_LIST`) one indirection away
+ * from where R1 looks, which is why no audit caught it.
+ *
+ * They had nothing to protect. `PayoutBankAccount` declares exactly
+ * `accountHolderName`, `accountNumberMasked`, `ifscCode`, `bankName` — the
+ * number is masked by definition and the rest are public bank identifiers. The
+ * real `accountNumber` lives on `UserDocument.payoutDetails`, encrypted there
+ * by `encryptPayoutDetails`, and is deliberately NOT copied onto a payout.
+ *
+ * The danger was the name: it read as protection, so a caller could reasonably
+ * pass a real account number through it and believe it had been encrypted.
+ * `seller-actions.ts` did exactly that — it copied the whole `bankAccount`,
+ * including the encrypted `accountNumber`, and the no-op stored the ciphertext
+ * verbatim where nothing would ever unwrap it.
+ *
+ * `accountHolderName` is still masked for list views, by `maskedPayout`.
  */
-export function decryptPayoutBankAccount(bank) {
-    if (!bank)
-        return bank;
-    return decryptPiiFields({ ...bank }, []);
-}

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

@@ -70,6 +70,24 @@ export declare function maskName(name: string | null | undefined): string;
  * "john.doe@example.com" → "j***@***.com"
  */
 export declare function maskEmail(email: string | null | undefined): string;
+/**
+ * Mask a phone number for display. Keeps the last four digits, which is the
+ * convention every support flow in this codebase already reads out loud.
+ *
+ * "+91 98765 43210" → "***43210"  (digits only, so formatting cannot leak)
+ *
+ * 🛑 Same `hasEncPrefix` guard as its siblings: if the value is still a
+ * ciphertext blob, return a fully-masked placeholder rather than a prefix of
+ * base64. Without it, "***" + the last four characters of an `enc:v1:` payload
+ * would read as a real phone number and be wrong in a way nobody could spot.
+ *
+ * A private copy of this already existed in `pii-redact.ts` for LOG redaction.
+ * That one is deliberately left alone: it has no encryption guard because logs
+ * are written from plaintext in memory, and giving the two one implementation
+ * would mean one of the callers getting a guard it does not need or losing one
+ * it does.
+ */
+export declare function maskPhone(phone: string | null | undefined): string;
 /**
  * Return a copy of a review document with PII fields masked for public display.
  * Admin/owner endpoints should NOT call this — use the raw document instead.

package/dist/security/pii-mask.js

@@ -87,6 +87,33 @@ export function maskEmail(email) {
     const domainMasked = dotIdx > 0 ? "***" + domain.slice(dotIdx) : "***";
     return (local[0] ?? "*") + "***@" + domainMasked;
 }
+/**
+ * Mask a phone number for display. Keeps the last four digits, which is the
+ * convention every support flow in this codebase already reads out loud.
+ *
+ * "+91 98765 43210" → "***43210"  (digits only, so formatting cannot leak)
+ *
+ * 🛑 Same `hasEncPrefix` guard as its siblings: if the value is still a
+ * ciphertext blob, return a fully-masked placeholder rather than a prefix of
+ * base64. Without it, "***" + the last four characters of an `enc:v1:` payload
+ * would read as a real phone number and be wrong in a way nobody could spot.
+ *
+ * A private copy of this already existed in `pii-redact.ts` for LOG redaction.
+ * That one is deliberately left alone: it has no encryption guard because logs
+ * are written from plaintext in memory, and giving the two one implementation
+ * would mean one of the callers getting a guard it does not need or losing one
+ * it does.
+ */
+export function maskPhone(phone) {
+    if (!phone || typeof phone !== "string")
+        return "***";
+    if (hasEncPrefix(phone))
+        return "***";
+    const digits = phone.replace(/\D/g, "");
+    if (digits.length < 4)
+        return "***";
+    return `***${digits.slice(-4)}`;
+}
 /**
  * Return a copy of a review document with PII fields masked for public display.
  * Admin/owner endpoints should NOT call this — use the raw document instead.

package/dist/seed/_helpers/search-txt-wrappers.d.ts

@@ -3,10 +3,10 @@ import type { StoreDocument } from "../../features/stores/schemas/firestore";
 import type { ScammerDocument } from "../../features/scams/schemas/firestore";
 import type { EventDocument } from "../../features/events/schemas/firestore";
 import type { BlogPostDocument } from "../../features/blog/schemas/firestore";
-import type { ReviewDocument } from "../../features/reviews/schemas/firestore";
-import type { OrderDocument } from "../../features/orders/schemas/firestore";
+import type { ReviewPlain } from "../../features/reviews/schemas/firestore";
+import type { OrderPlain } from "../../features/orders/schemas/firestore";
 import type { CouponDocument } from "../../features/promotions/schemas/firestore";
-import type { OfferDocument } from "../../features/seller/schemas/firestore";
+import type { OfferPlain } from "../../features/seller/schemas/firestore";
 /**
  * 🛑 Apply AFTER `buildCategoryTree`, never before.
  *
@@ -19,8 +19,8 @@ export declare function withCategorySearchTxt<T extends Partial<CategoryDocument
 export declare function withStoreSearchTxt<T extends Partial<StoreDocument>>(p: T): T;
 export declare function withEventSearchTxt<T extends Partial<EventDocument>>(p: T): T;
 export declare function withBlogSearchTxt<T extends Partial<BlogPostDocument>>(p: T): T;
-export declare function withReviewSearchTxt<T extends Partial<ReviewDocument>>(p: T): T;
-export declare function withOrderSearchTxt<T extends Partial<OrderDocument>>(p: T): T;
+export declare function withReviewSearchTxt<T extends Partial<ReviewPlain>>(p: T): T;
+export declare function withOrderSearchTxt<T extends Partial<OrderPlain>>(p: T): T;
 export declare function withCouponSearchTxt<T extends Partial<CouponDocument>>(p: T): T;
-export declare function withOfferSearchTxt<T extends Partial<OfferDocument>>(p: T): T;
+export declare function withOfferSearchTxt<T extends Partial<OfferPlain>>(p: T): T;
 export declare function withScammerSearchTxt<T extends Partial<ScammerDocument>>(p: T): T;

package/dist/seed/_helpers/search-txt-wrappers.js

@@ -19,15 +19,37 @@ export function withEventSearchTxt(p) {
 export function withBlogSearchTxt(p) {
     return { ...p, searchTxt: buildBlogSearchTxt(p) };
 }
+/*
+ * Bounded by `ReviewPlain` for the same reason as the offer wrapper: seed
+ * fixtures hold plaintext and `seed-cli` encrypts on write, and
+ * `string`/`Encrypted<string>` are incompatible in both directions.
+ * `buildReviewSearchTxt` deliberately does NOT read `userName` — it is
+ * encrypted, and indexing it would undo the encryption (D1).
+ */
 export function withReviewSearchTxt(p) {
     return { ...p, searchTxt: buildReviewSearchTxt(p) };
 }
+/*
+ * Bounded by `OrderPlain`: seed fixtures hold plaintext and `seed-cli`
+ * encrypts on write. `buildOrderSearchTxt` reads the product, store, tracking
+ * number, items and location — never `userEmail` (D1).
+ */
 export function withOrderSearchTxt(p) {
     return { ...p, searchTxt: buildOrderSearchTxt(p) };
 }
 export function withCouponSearchTxt(p) {
     return { ...p, searchTxt: buildCouponSearchTxt(p) };
 }
+/*
+ * Bounded by `OfferPlain`, not `OfferDocument`.
+ *
+ * Seed fixtures hold plaintext and `seed-cli` encrypts on write, so the array
+ * this maps over is `Partial<OfferPlain>[]`. `string` and `Encrypted<string>`
+ * are incompatible in both directions, so a document-bounded generic rejects
+ * the plain shape outright. The function reads `buyerName` for tokens and does
+ * not care which it gets — and `buildOfferSearchTxt` is deliberately given the
+ * PLAINTEXT one: tokenising ciphertext would index base64.
+ */
 export function withOfferSearchTxt(p) {
     return { ...p, searchTxt: buildOfferSearchTxt(p) };
 }

package/dist/seed/addresses-seed-data.d.ts

@@ -1,2 +1,2 @@
-import type { AddressDocument } from "../features/addresses/schemas/firestore";
-export declare const addressesSeedData: AddressDocument[];
+import type { AddressPlain } from "../features/addresses/schemas/firestore";
+export declare const addressesSeedData: AddressPlain[];

package/dist/seed/authenticity-knowledge-seed-data.d.ts

@@ -0,0 +1,34 @@
+export declare const AUTHENTICITY_KNOWLEDGE_COLLECTION = "authenticityKnowledge";
+/** A date-code row, a generation summary, or (future) a marque. */
+export type AuthenticityKnowledgeKind = "date-code" | "generation" | "marque";
+/**
+ * What the community has recorded about a box code.
+ *
+ * 🛑 `recorded-midfake` is a statement about a BATCH, never about a seller, and
+ * never "counterfeit". A midfake is Takara-Tomy-blueprint product of reduced
+ * quality and there is no official Takara Tomy statement acknowledging the runs.
+ */
+export type AuthenticityCodeVerdict = "recorded-original" | "recorded-midfake" | "unresolved";
+export interface AuthenticityKnowledgeDocument {
+    id: string;
+    kind: AuthenticityKnowledgeKind;
+    seedPurpose: "permanent";
+    /** date-code rows only. */
+    code?: string;
+    verdict?: AuthenticityCodeVerdict;
+    products?: string[];
+    distributors?: string[];
+    /** Derived FROM the code under the disputed month-day-year reading. */
+    derivedDate?: string | null;
+    /** True where the source's own written date contradicts its own stated rule. */
+    sourceDateDiffers?: boolean;
+    generation?: string;
+    /** generation rows only. */
+    canonicalReleaseCount?: number;
+    releasesWithRetailCode?: number;
+    exampleCodes?: string[];
+    hasDateCodeTable?: boolean;
+}
+export declare const authenticityKnowledgeSeedData: AuthenticityKnowledgeDocument[];
+/** Asserted downstream so a silent drop is loud. */
+export declare const AUTHENTICITY_KNOWLEDGE_COUNT = 104;