@mohasinac/appkit 4.52.5 → 4.53.0

package/dist/security/encrypted.js

@@ -0,0 +1,100 @@
+/**
+ * `Encrypted<T>` — the FORCING FUNCTION for ciphertext-by-default.
+ *
+ * ## The problem this exists to solve
+ *
+ * `audit-pii-coverage`'s R3 stages fourteen repositories whose `mapDoc`
+ * decrypts PII on EVERY read. The prescription — copy `SiteSettingsRepository`:
+ * leave `mapDoc` alone and expose plaintext through a NAMED getter with a
+ * masked variant — is right, and the migration had been staged for one reason:
+ *
+ *   **`tsc` cannot find the call sites.**
+ *
+ * Measured 2026-10-17: 147 distinct files touch a staged repository. And
+ * `PayoutDocument.sellerEmail` is declared `string` whether the value in it is
+ * ciphertext or plaintext, so a call site that gets the wrong one COMPILES. It
+ * then either renders `enc:v1:…` to an admin or publishes a decrypted email.
+ * There is no compile error, no runtime error, and nothing to grep for.
+ *
+ * Compare the `perPage` → `pageSize` rename done the same day: renaming one
+ * interface member turned all 65 consumers into compile errors and `tsc`
+ * handed over the list. That is the difference between a safe sweep and a
+ * 147-file guess, and it is purely a property of the TYPE.
+ *
+ * ## How it works
+ *
+ * A branded string. `Encrypted<string>` is assignable FROM nothing but itself,
+ * so every reader that wants a plain `string` must go through one of the two
+ * named accessors below — and until it does, it is a compile error naming the
+ * exact file and line.
+ *
+ * ```ts
+ * //   payout.sellerEmail            → Encrypted<string>   (what Firestore holds)
+ * //   plaintext(payout.sellerEmail) → string              (opt-in, named, auditable)
+ * //   maskedEmail(payout.sellerEmail) → string            (the UI default)
+ * ```
+ *
+ * The brand is erased at runtime: `Encrypted<string>` IS a string, so nothing
+ * changes about what is stored, sent or compared. It exists only to make the
+ * compiler ask the question at every site.
+ *
+ * ## 🛑 Branding a field is HALF a change, never a whole one
+ *
+ * The type must be made true in the same commit, by removing that
+ * repository's unconditional `mapDoc` decrypt. Branding a field whose value is
+ * still decrypted on read asserts something false, and the first `plaintext()`
+ * call would then double-decrypt — `decryptValue` passes a non-`enc:v1:`
+ * string through unchanged, so it would silently "work" and hide the lie.
+ *
+ * Convert ONE repository per change, smallest consumer count first. `tsc` then
+ * enumerates only that repository's readers, which is the whole point: a
+ * reviewable list per step instead of 147 at once.
+ */
+/**
+ * Mark a value as ciphertext. For a repository's own read path, where the value
+ * genuinely came out of Firestore encrypted.
+ *
+ * 🛑 Not for widening a plaintext value to satisfy a type. If a caller has
+ * plaintext and the field wants `Encrypted`, the value needs ENCRYPTING, not
+ * re-labelling — `encryptPii` is the function for that.
+ */
+export const asEncrypted = (value) => 
+/*
+ * `as unknown as` is REQUIRED here, and only here.
+ *
+ * With the nominal brand, `Encrypted<T>` is not a string type, so a direct
+ * cast is a TS2352 ("neither type sufficiently overlaps"). That error is
+ * correct and is the entire point of the nominal shape — this one function
+ * is the sanctioned crossing, which is why the double cast is confined to it
+ * rather than appearing at call sites.
+ *
+ * Its four real callers all pass `""` to BLANK a field on a display-only
+ * read, not to relabel a secret.
+ */
+value;
+/**
+ * Narrow a possibly-undefined ciphertext field. Saves every call site writing
+ * the same `value === undefined ? undefined : …` dance.
+ */
+export const asEncryptedMaybe = (value) => value === undefined || value === null ? undefined : asEncrypted(value);
+/*
+ * 🛑 There is deliberately NO `plaintext(value)` helper in this module.
+ *
+ * The first draft had one, and it was a lie of exactly the kind this whole
+ * sweep exists to remove: it took an `Encrypted<string>` and returned
+ * `string` by casting — so a function named `plaintext` handed back
+ * CIPHERTEXT, and every caller would have rendered `enc:v1:…` while the types
+ * said everything was fine. `decryptValue` passes a non-`enc:v1:` string
+ * through unchanged, so it would even have "worked" on the rows that were
+ * never encrypted, and failed only on the ones that were.
+ *
+ * Decryption needs the key and `node:crypto`, which belong to the server; this
+ * module is types-only so it stays importable from a client bundle (Root Cause
+ * #24). So the plaintext path lives where the decryption actually happens:
+ *
+ *   on the REPOSITORY, as a named method, following `SiteSettingsRepository` —
+ *   `getDecryptedCredentials()` / `getCredentialsMasked()`.
+ *
+ * Masked is the default a UI should reach for; plaintext is opt-in and named,
+ * so it shows up both in review and in a grep.
+ */

package/dist/security/index.d.ts

@@ -4,7 +4,10 @@ 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, piiIndicesFor, getPiiConfigError, 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 { asEncrypted, asEncryptedMaybe } from "./encrypted";
+export type { Encrypted } from "./encrypted";
+export { encryptValue, decryptValue, hmacBlindIndex, encryptPiiFields, decryptPiiFields, encryptPii, decryptPii, piiBlindIndex, piiIndicesFor, getPiiConfigError, encryptPayoutDetails, decryptPayoutDetails, encryptShippingConfig, decryptShippingConfig, } from "./pii-encrypt";
+export { revealPii, maskPii, revealPiiAll, maskPiiAll } from "./pii-accessors";
+export { isPiiEncrypted, maskName, maskEmail, maskPhone, 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, TOKEN_PII_FIELDS, TOKEN_PII_INDEX_MAP, REVIEW_PII_FIELDS, REVIEW_PII_INDEX_MAP, OFFER_PII_FIELDS, EVENT_ENTRY_PII_FIELDS, LOTTERY_ENTRY_PII_FIELDS, PAYMENT_METHOD_PII_FIELDS, CONVERSATION_PII_FIELDS, MESSAGE_PII_FIELDS, } from "./pii-schemas";
 export { encryptSecret, decryptSecret, isSecretEncrypted, maskSecret, } from "./settings-encryption";

package/dist/security/index.js

@@ -2,11 +2,25 @@ export { generateNonce, buildCSP } from "./csp.js";
 export { rateLimit, applyRateLimit, rateLimitByIdentifier, RateLimitPresets, clearRateLimitStore, getClientIP, hashGuestIdentity, } from "./rate-limit.js";
 export { requireAuth, requireRole, requireOwnership, requireEmailVerified, requireActiveAccount, canChangeRole, getRoleLevel, } from "./authorization.js";
 export { redactPii, safeDisplayName, safeDisplayEmail, maskIp } from "./pii-redact.js";
-export { encryptValue, decryptValue, hmacBlindIndex, encryptPiiFields, decryptPiiFields, encryptPii, decryptPii, piiBlindIndex, piiIndicesFor, getPiiConfigError, encryptPayoutDetails, decryptPayoutDetails, encryptShippingConfig, decryptShippingConfig, encryptPayoutBankAccount, decryptPayoutBankAccount, } from "./pii-encrypt.js";
+/*
+ * The ciphertext-by-default forcing function. Types + two labelling helpers
+ * only — no crypto — so this stays safe in the universal barrel (Root Cause
+ * #24). See `encrypted.ts` for why `tsc` has to be the thing that enumerates
+ * the 147 call sites, and why there is no `plaintext()` free function.
+ */
+export { asEncrypted, asEncryptedMaybe } from "./encrypted.js";
+export { encryptValue, decryptValue, hmacBlindIndex, encryptPiiFields, decryptPiiFields, encryptPii, decryptPii, piiBlindIndex, piiIndicesFor, getPiiConfigError, encryptPayoutDetails, decryptPayoutDetails, encryptShippingConfig, decryptShippingConfig, } from "./pii-encrypt.js";
+/*
+ * The two NAMED PII accessors that replace an unconditional `mapDoc` decrypt.
+ * Server-only — they import `pii-encrypt`, which reaches node:crypto through a
+ * bare runtime require (Root Cause #24), so this must never be re-exported
+ * from the universal client entry.
+ */
+export { revealPii, maskPii, revealPiiAll, maskPiiAll } from "./pii-accessors.js";
 // 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.js";
+export { isPiiEncrypted, maskName, maskEmail, maskPhone, maskPublicReview, maskPublicBid, maskPublicEventEntry, maskOfferForSeller, ENC_PREFIX, HMAC_PREFIX, } from "./pii-mask.js";
 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, EVENT_ENTRY_PII_FIELDS, LOTTERY_ENTRY_PII_FIELDS, PAYMENT_METHOD_PII_FIELDS, CONVERSATION_PII_FIELDS, MESSAGE_PII_FIELDS, } from "./pii-schemas.js";
 export { encryptSecret, decryptSecret, isSecretEncrypted, maskSecret, } from "./settings-encryption.js";
 // RBAC system — DELETED 2026-08-29.

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

@@ -0,0 +1,71 @@
+/**
+ * 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
+ */
+/**
+ * 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 declare function revealPii<Plain extends object>(doc: object, piiFields: readonly string[]): Plain;
+/**
+ * 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 declare function maskPii<Plain extends object>(doc: object, piiFields: readonly string[]): Plain;
+/** Array form of `revealPii`, for list reads. */
+export declare function revealPiiAll<Plain extends object>(docs: readonly object[], piiFields: readonly string[]): Plain[];
+/** Array form of `maskPii`, for list reads. */
+export declare function maskPiiAll<Plain extends object>(docs: readonly object[], piiFields: readonly string[]): Plain[];

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;