@mohasinac/appkit 4.52.4 → 4.53.0

package/dist/features/auctions/repository/bid.repository.d.ts

@@ -5,8 +5,9 @@
  */
 import { BaseRepository, parseSieveDateValue } from "../../../providers/db-firebase";
 import type { DocumentReference, WriteBatch } from "firebase-admin/firestore";
+import type { JsonValue } from "../../../schemas/types";
 import type { SieveModel, FirebaseSieveResult } from "../../../providers/db-firebase";
-import type { BidDocument, BidCreateInput, BidUpdateInput, BidAdminUpdateInput, BidStatus } from "../schemas";
+import type { BidDocument, BidPlain, BidCreateInput, BidUpdateInput, BidAdminUpdateInput, BidStatus } from "../schemas";
 import { type HistoryActor } from "../../../_internal/shared/history/index";
 /** Who/why for a bid write that lands in `statusHistory`. */
 export interface BidWriteContext {
@@ -37,11 +38,23 @@ export declare class BidRepository extends BaseRepository<BidDocument> {
      */
     protected piiFields: readonly ["userEmail"];
     /** Override mapDoc to auto-decrypt PII on every bid read */
-    protected mapDoc<D = BidDocument>(snap: import("../../../providers/db-firebase").DocumentSnapshot): D;
+    /** Plaintext PII. **Opt-in and named** — shows up in review and in a grep. */
+    revealBid(doc: BidDocument): BidPlain;
+    /** As `revealBid`, for a list read. */
+    revealBids(docs: readonly BidDocument[]): BidPlain[];
+    /**
+     * Masked PII — **the default for any surface that only needs to identify a
+     * row to a human.** Decrypts first, then masks: the mask helpers refuse
+     * ciphertext by design, so passing a stored field straight in would return
+     * "Anonymous" for every row.
+     */
+    maskedBid(doc: BidDocument): BidPlain;
+    /** As `maskedBid`, for a list read. */
+    maskedBids(docs: readonly BidDocument[]): BidPlain[];
     /**
      * Create new bid with auto-generated ID
      */
-    create(input: BidCreateInput): Promise<BidDocument>;
+    createBid(input: BidCreateInput): Promise<BidPlain>;
     /**
      * Find bids by product ID
      */
@@ -179,6 +192,10 @@ export declare class BidRepository extends BaseRepository<BidDocument> {
             canFilter: boolean;
             canSort: boolean;
         };
+        searchTxt: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
         userEmail: {
             canFilter: boolean;
             canSort: boolean;
@@ -209,6 +226,31 @@ export declare class BidRepository extends BaseRepository<BidDocument> {
     /**
      * Paginated, Firestore-native bid list (admin use).
      */
-    list(model: SieveModel): Promise<FirebaseSieveResult<BidDocument>>;
+    /** Derived on every write path via `applyWriteHooks`. */
+    protected buildSearchTxtFor(data: Record<string, JsonValue>): string[] | null;
+    /**
+     * `opts.search` is a searchTxt PUSHDOWN, not a Sieve clause.
+     *
+     * ## What this replaces, on both of its two surfaces
+     *
+     * `/api/store/bids` searched the bidder with `userName@=`, a CASE-SENSITIVE
+     * prefix — the only thing Firestore can do for a prefix — so a seller typing
+     * "ravi" did not find "Ravi", and "kumar" never found anyone at all.
+     * `/api/user/bids` filtered `productTitle.includes(q)` in memory AFTER
+     * paging, so a match on page 2 was unreachable.
+     *
+     * Token search fixes both: `buildSearchTxt` normalises case and indexes word
+     * prefixes, so the query and the index meet on tokens rather than on a
+     * substring of one field.
+     *
+     * 🛑 `planSearchTxt`'s `empty` guard is the load-bearing part. A query that
+     * normalises to no usable token (`"!!!"`, `"—"`) MUST return nothing —
+     * emitting no clause instead returns the whole collection and calls it a
+     * search result, which is the shape of every silent-search bug in this
+     * codebase.
+     */
+    list(model: SieveModel, opts?: {
+        search?: string;
+    }): Promise<FirebaseSieveResult<BidDocument>>;
 }
 export declare const bidRepository: BidRepository;

package/dist/features/auctions/repository/bid.repository.js

@@ -4,11 +4,13 @@ import { normalizeError } from "../../../errors/normalize.js";
  *
  * Data access layer for bid documents in Firestore
  */
-import { BaseRepository, getFirestoreCount, prepareForFirestore, parseSieveDateValue, } from "../../../providers/db-firebase/index.js";
+import { BaseRepository, getFirestoreCount, prepareForFirestore, parseSieveDateValue, applySieveToFirestore, } from "../../../providers/db-firebase/index.js";
 import { DatabaseError } from "../../../errors/index.js";
+import { buildBidSearchTxt } from "../../../utils/search-txt-builders.js";
+import { planSearchTxt, beginSearchWindow, emptySearchResult, } from "../../../utils/search-txt-query.js";
 import { BID_COLLECTION, BID_TRACKED_FIELDS, BID_HISTORY_PII_FIELDS, createBidId } from "../schemas/index.js";
 import { withHistory } from "../../../_internal/shared/history/index.js";
-import { decryptPiiFields, BID_PII_FIELDS, } from "../../../security/index.js";
+import { BID_PII_FIELDS, maskPii, revealPii, } from "../../../security/index.js";
 import { BID_FIELDS } from "../../../constants/field-names.js";
 export class BidRepository extends BaseRepository {
     constructor() {
@@ -34,22 +36,64 @@ export class BidRepository extends BaseRepository {
         this.piiFields = BID_PII_FIELDS;
     }
     /** Override mapDoc to auto-decrypt PII on every bid read */
-    mapDoc(snap) {
-        const raw = super.mapDoc(snap);
-        return decryptPiiFields(raw, [
-            ...BID_PII_FIELDS,
-        ]);
+    /*
+     * 🛑 `mapDoc` is NOT overridden, and that absence IS the change.
+     *
+     * It used to decrypt on every read, so ciphertext never left the database
+     * and every caller handled plaintext without ever saying so. Following
+     * `SiteSettingsRepository`: reads return what Firestore holds, and plaintext
+     * requires one of the two named methods below.
+     *
+     * A convention would not hold this. `BidDocument`'s PII fields are
+     * `Encrypted<string>`, assignable to nothing that wants a plain `string`, so
+     * a reader that skips both accessors is a compile error naming file and line.
+     */
+    /** Plaintext PII. **Opt-in and named** — shows up in review and in a grep. */
+    revealBid(doc) {
+        return revealPii(doc, BID_PII_FIELDS);
+    }
+    /** As `revealBid`, for a list read. */
+    revealBids(docs) {
+        return docs.map((d) => this.revealBid(d));
+    }
+    /**
+     * Masked PII — **the default for any surface that only needs to identify a
+     * row to a human.** Decrypts first, then masks: the mask helpers refuse
+     * ciphertext by design, so passing a stored field straight in would return
+     * "Anonymous" for every row.
+     */
+    maskedBid(doc) {
+        return maskPii(doc, BID_PII_FIELDS);
+    }
+    /** As `maskedBid`, for a list read. */
+    maskedBids(docs) {
+        return docs.map((d) => this.maskedBid(d));
     }
     /**
      * Create new bid with auto-generated ID
      */
-    async create(input) {
+    /*
+     * 🛑 NOT an `override` of `create`, and the rename is forced rather than
+     * stylistic.
+     *
+     * `BaseRepository.create` is declared `(data: Partial<Doc> | FirestoreDocument)`,
+     * i.e. it promises to accept the CIPHERTEXT shape. This method accepts
+     * PLAINTEXT and encrypts. `string` and `Encrypted<string>` are incompatible
+     * in both directions, so an override is a TS2416 no matter which way the
+     * check runs — and it should be, because the two signatures genuinely
+     * disagree about what the caller is holding.
+     *
+     * Five call sites across both repositories; `create` remains inherited for
+     * anything that legitimately has ciphertext already.
+     */
+    async createBid(input) {
         const bidIdInput = {
             productName: input.productTitle,
             userFirstName: input.userName.split(" ")[0] || input.userName,
             date: new Date(),
         };
         const id = createBidId(bidIdInput);
+        // Plain in, ciphertext out — the write hook encrypts below.
         const bidData = {
             ...input,
             status: "active",
@@ -64,7 +108,16 @@ export class BidRepository extends BaseRepository {
             .collection(this.collection)
             .doc(id)
             .set(prepareForFirestore(encrypted));
-        return { id, ...bidData }; // return plaintext to caller
+        /*
+          * Returns `BidPlain`, and the declared type now says so.
+          *
+          * This line's own comment has always read "return plaintext to caller"
+          * while the signature promised `BidDocument` — the exact mismatch
+          * `Encrypted<string>` exists to surface. It echoes the input rather than
+          * re-reading, which is deliberate (a read-after-write costs a Firestore
+          * read on every bid), so what comes back is the plaintext that went in.
+          */
+        return { id, ...bidData };
     }
     /**
      * Find bids by product ID
@@ -441,11 +494,53 @@ export class BidRepository extends BaseRepository {
     /**
      * Paginated, Firestore-native bid list (admin use).
      */
-    async list(model) {
-        return this.sieveQuery(model, BidRepository.SIEVE_FIELDS, {
-            defaultPageSize: 50,
-            maxPageSize: 200,
+    /** Derived on every write path via `applyWriteHooks`. */
+    buildSearchTxtFor(data) {
+        return buildBidSearchTxt(data);
+    }
+    /**
+     * `opts.search` is a searchTxt PUSHDOWN, not a Sieve clause.
+     *
+     * ## What this replaces, on both of its two surfaces
+     *
+     * `/api/store/bids` searched the bidder with `userName@=`, a CASE-SENSITIVE
+     * prefix — the only thing Firestore can do for a prefix — so a seller typing
+     * "ravi" did not find "Ravi", and "kumar" never found anyone at all.
+     * `/api/user/bids` filtered `productTitle.includes(q)` in memory AFTER
+     * paging, so a match on page 2 was unreachable.
+     *
+     * Token search fixes both: `buildSearchTxt` normalises case and indexes word
+     * prefixes, so the query and the index meet on tokens rather than on a
+     * substring of one field.
+     *
+     * 🛑 `planSearchTxt`'s `empty` guard is the load-bearing part. A query that
+     * normalises to no usable token (`"!!!"`, `"—"`) MUST return nothing —
+     * emitting no clause instead returns the whole collection and calls it a
+     * search result, which is the shape of every silent-search bug in this
+     * codebase.
+     */
+    async list(model, opts) {
+        const plan = planSearchTxt(opts?.search);
+        if (plan.empty)
+            return emptySearchResult();
+        if (!plan.head) {
+            return this.sieveQuery(model, BidRepository.SIEVE_FIELDS, {
+                defaultPageSize: 50,
+                maxPageSize: 200,
+            });
+        }
+        const baseQuery = this.getCollection().where("searchTxt", "array-contains", plan.head);
+        // One bounded window, one raised maxPageSize, one page slice — hand-rolling
+        // the three is how other repositories each ended up with two of them.
+        const win = beginSearchWindow(model, plan);
+        const result = await applySieveToFirestore({
+            baseQuery,
+            model: win.model,
+            options: { maxPageSize: win.maxPageSize(200) },
+            fields: BidRepository.SIEVE_FIELDS,
+            mapDoc: (snap) => this.mapDoc(snap),
         });
+        return win.finish(result);
     }
 }
 // ---------------------------------------------------------------------------
@@ -457,6 +552,12 @@ BidRepository.SIEVE_FIELDS = {
     productTitle: { canFilter: true, canSort: true },
     userId: { canFilter: true, canSort: false },
     userName: { canFilter: true, canSort: true },
+    /*
+     * Filterable so the grammar admits it; the real read is an
+     * `array-contains` pushdown in `list()`, not a Sieve clause — Sieve cannot
+     * express array membership.
+     */
+    searchTxt: { canFilter: true, canSort: false },
     // Encrypted (BID_PII_FIELDS). Filtering compares plaintext against
     // `enc:v1:…` and matches ZERO rows with a 200; sorting orders by base64
     // noise. It appeared to work only because the column was still

package/dist/features/auctions/schemas/firestore.d.ts

@@ -4,6 +4,7 @@
 import { type GenerateBidIdInput } from "../../../utils/id-generators";
 import type { StatusChangeEntry } from "../../../_internal/shared/history/types";
 import type { BaseDocument } from "../../../_internal/shared/types/base-document";
+import type { Encrypted, Plaintext } from "../../../security/encrypted";
 export type BidStatus = "active" | "outbid" | "won" | "lost" | "cancelled"
 /** Won, then the buyer let the 48h payment window lapse. */
  | "forfeited";
@@ -16,12 +17,22 @@ export declare const BidStatusValues: {
     readonly CANCELLED: "cancelled";
     readonly FORFEITED: "forfeited";
 };
+/**
+ * `BidDocument` with its PII as plain `string` — what the named repository
+ * accessors return, and what a WRITE path accepts (the repository encrypts).
+ *
+ * `Plaintext<T>` is the one definition of this shape; see `security/encrypted.ts`.
+ * It is deliberately NOT distinguishable from a MASKED value — `maskPii`
+ * returns plain strings too, and no type can express "these characters are
+ * asterisks". The distinction is which named method you called.
+ */
+export type BidPlain = Plaintext<BidDocument>;
 export interface BidDocument extends BaseDocument {
     productId: string;
     productTitle: string;
     userId: string;
     userName: string;
-    userEmail: string;
+    userEmail: Encrypted<string>;
     bidAmount: number;
     currency: string;
     status: BidStatus;
@@ -29,6 +40,15 @@ export interface BidDocument extends BaseDocument {
     previousBidAmount?: number;
     bidDate: Date;
     autoMaxBid?: number;
+    /**
+     * Token index over `productTitle` + `userName`, derived on every write.
+     *
+     * 🛑 `userEmail` is deliberately ABSENT — it is the one entry in
+     * `BID_PII_FIELDS`, and a searchTxt over an encrypted field IS that field in
+     * plaintext (decision D1). `userName` is not in that registry and is already
+     * in `BID_PUBLIC_FIELDS`, so indexing it discloses nothing new.
+     */
+    searchTxt?: string[];
     /**
      * The order this winning bid was settled into. Written by
      * `finalizeLockedLines` once the winner actually pays; absent on a won-but-
@@ -65,13 +85,13 @@ export interface BidDocument extends BaseDocument {
     statusHistoryTruncated?: number;
 }
 export declare const BID_COLLECTION: "bids";
-export declare const BID_INDEXED_FIELDS: readonly ["productId", "userId", "status", "isWinning", "bidDate", "createdAt"];
+export declare const BID_INDEXED_FIELDS: readonly ["productId", "userId", "status", "isWinning", "bidDate", "createdAt", "searchTxt"];
 export declare const DEFAULT_BID_DATA: Partial<BidDocument>;
 export declare const BID_PUBLIC_FIELDS: readonly ["id", "productId", "productTitle", "userName", "bidAmount", "currency", "bidDate", "isWinning", "createdAt"];
 export declare const BID_UPDATABLE_FIELDS: readonly ["autoMaxBid"];
-export type BidCreateInput = Omit<BidDocument, "id" | "createdAt" | "updatedAt" | "status" | "isWinning">;
+export type BidCreateInput = Omit<BidPlain, "id" | "createdAt" | "updatedAt" | "status" | "isWinning">;
 export type BidUpdateInput = Partial<Pick<BidDocument, (typeof BID_UPDATABLE_FIELDS)[number]>>;
-export type BidAdminUpdateInput = Partial<Omit<BidDocument, "id" | "createdAt">>;
+export type BidAdminUpdateInput = Partial<Omit<BidPlain, "id" | "createdAt">>;
 export declare const bidQueryHelpers: {
     readonly byProduct: (productId: string) => readonly ["productId", "==", string];
     readonly byUser: (userId: string) => readonly ["userId", "==", string];

package/dist/features/auctions/schemas/firestore.js

@@ -19,6 +19,7 @@ export const BID_INDEXED_FIELDS = [
     "isWinning",
     "bidDate",
     "createdAt",
+    "searchTxt",
 ];
 export const DEFAULT_BID_DATA = {
     status: "active",

package/dist/features/auth/actions/profile-actions.js

@@ -5,7 +5,6 @@
  * Auth, rate-limiting, and Next.js specifics are handled by the consumer.
  */
 import { cache } from "react";
-import { maskPublicReview } from "../../../security/index.js";
 import { safeRead } from "../../../errors/safe-read.js";
 import { finalizeStagedMediaField } from "../../media/finalize.js";
 import { userRepository } from "../repository/user.repository.js";
@@ -86,7 +85,16 @@ export async function getSellerReviews(storeId) {
         productId: r.productId,
         productTitle: r.productTitle,
         userId: r.userId,
-        userName: maskPublicReview(r).userName,
+        /*
+         * 🛑 `maskedReview`, not `maskPublicReview`.
+         *
+         * `maskPublicReview` calls `maskName`, which refuses a ciphertext input by
+         * design and answers "Anonymous". Since `ReviewRepository.mapDoc` stopped
+         * decrypting, `r.userName` IS ciphertext — so this rendered every reviewer
+         * on every public profile as "Anonymous". `maskedReview` decrypts first,
+         * then masks, which is the whole reason it exists.
+         */
+        userName: reviewRepository.maskedReview(r).userName,
         userAvatar: r.userAvatar,
         rating: r.rating,
         title: r.title,
@@ -117,7 +125,16 @@ export async function getReviewsAuthoredBy(userId) {
         productId: r.productId,
         productTitle: r.productTitle,
         userId: r.userId,
-        userName: maskPublicReview(r).userName,
+        /*
+         * 🛑 `maskedReview`, not `maskPublicReview`.
+         *
+         * `maskPublicReview` calls `maskName`, which refuses a ciphertext input by
+         * design and answers "Anonymous". Since `ReviewRepository.mapDoc` stopped
+         * decrypting, `r.userName` IS ciphertext — so this rendered every reviewer
+         * on every public profile as "Anonymous". `maskedReview` decrypts first,
+         * then masks, which is the whole reason it exists.
+         */
+        userName: reviewRepository.maskedReview(r).userName,
         userAvatar: r.userAvatar,
         rating: r.rating,
         title: r.title,
@@ -142,7 +159,16 @@ export async function getReviewsReceivedBy(userId) {
         productId: r.productId,
         productTitle: r.productTitle,
         userId: r.userId,
-        userName: maskPublicReview(r).userName,
+        /*
+         * 🛑 `maskedReview`, not `maskPublicReview`.
+         *
+         * `maskPublicReview` calls `maskName`, which refuses a ciphertext input by
+         * design and answers "Anonymous". Since `ReviewRepository.mapDoc` stopped
+         * decrypting, `r.userName` IS ciphertext — so this rendered every reviewer
+         * on every public profile as "Anonymous". `maskedReview` decrypts first,
+         * then masks, which is the whole reason it exists.
+         */
+        userName: reviewRepository.maskedReview(r).userName,
         userAvatar: r.userAvatar,
         rating: r.rating,
         title: r.title,

package/dist/features/auth/components/index.d.ts

@@ -1,7 +1,6 @@
 export { RoleGate, ProtectedRoute } from "./Guards";
 export type { RoleGateProps, ProtectedRouteProps, AuthGuardUser, AuthRouteConfig, } from "./Guards";
 export { SocialAuthButtons } from "./SocialAuthButtons";
-export { AuthStatusPanel } from "./AuthStatusPanel";
 export { LoginForm } from "./LoginForm";
 export type { LoginFormProps, LoginFormValues } from "./LoginForm";
 export { RegisterForm } from "./RegisterForm";

package/dist/features/auth/components/index.js

@@ -1,6 +1,5 @@
 export { RoleGate, ProtectedRoute } from "./Guards.js";
 export { SocialAuthButtons } from "./SocialAuthButtons.js";
-export { AuthStatusPanel } from "./AuthStatusPanel.js";
 export { LoginForm } from "./LoginForm.js";
 export { RegisterForm } from "./RegisterForm.js";
 export { ForgotPasswordView } from "./ForgotPasswordView.js";

package/dist/features/auth/repository/session.repository.d.ts

@@ -1,6 +1,6 @@
-import type { DocumentReference, DocumentSnapshot } from "firebase-admin/firestore";
+import type { DocumentReference } from "firebase-admin/firestore";
 import { BaseRepository, type FirebaseSieveFields, type FirebaseSieveResult, type SieveModel } from "../../../providers/db-firebase";
-import { type SessionCreateInput, type SessionDocument, type SessionUpdateInput } from "../schemas";
+import { type SessionCreateInput, type SessionDocument, type SessionPlain, type SessionUpdateInput } from "../schemas";
 export declare class SessionRepository extends BaseRepository<SessionDocument> {
     static readonly SIEVE_FIELDS: FirebaseSieveFields;
     /**
@@ -18,7 +18,21 @@ export declare class SessionRepository extends BaseRepository<SessionDocument> {
     protected piiFields: readonly ["deviceInfo.ip", "deviceInfo.userAgent", "location.city"];
     constructor();
     /** Decrypt on read so callers see the same shape they wrote. */
-    protected mapDoc<D = SessionDocument>(snap: DocumentSnapshot): D;
+    /**
+     * Plaintext PII. **Opt-in and named** — for the security page that shows a
+     * user their own sessions, and for abuse investigation.
+     */
+    revealSession(doc: SessionDocument): SessionPlain;
+    /** As `revealSession`, for a list read. */
+    revealSessions(docs: readonly SessionDocument[]): SessionPlain[];
+    /**
+     * Masked PII — the default. `deviceInfo.ip` becomes a last-four mask, which
+     * is what every admin surface here actually needs: enough to tell two
+     * sessions apart, not enough to geolocate a person.
+     */
+    maskedSession(doc: SessionDocument): SessionPlain;
+    /** As `maskedSession`, for a list read. */
+    maskedSessions(docs: readonly SessionDocument[]): SessionPlain[];
     list(model: SieveModel): Promise<FirebaseSieveResult<SessionDocument>>;
     listForUser(userId: string, model: SieveModel): Promise<FirebaseSieveResult<SessionDocument>>;
     createSession(userId: string, data: Omit<SessionCreateInput, "userId" | "expiresAt" | "isActive">): Promise<SessionDocument>;

package/dist/features/auth/repository/session.repository.js

@@ -3,7 +3,7 @@ import { DatabaseError } from "../../../errors/index.js";
 import { serverLogger } from "../../../monitoring/index.js";
 import { BaseRepository, parseSieveDateValue, } from "../../../providers/db-firebase/index.js";
 import { generateSessionId } from "../token-helpers.js";
-import { decryptPiiFields } from "../../../security/pii-encrypt.js";
+import { maskPii, revealPii } from "../../../security/pii-accessors.js";
 import { SESSION_COLLECTION, SESSION_EXPIRATION_MS, SESSION_FIELDS, } from "../schemas/index.js";
 export class SessionRepository extends BaseRepository {
     constructor() {
@@ -27,9 +27,36 @@ export class SessionRepository extends BaseRepository {
         ];
     }
     /** Decrypt on read so callers see the same shape they wrote. */
-    mapDoc(snap) {
-        const raw = super.mapDoc(snap);
-        return decryptPiiFields(raw, [...this.piiFields]);
+    /*
+     * 🛑 `mapDoc` is NOT overridden — it used to decrypt on every read, so the
+     * device IP and user-agent of every session left the database in the clear.
+     *
+     * All three PII fields here are NESTED, which is why `maskPii` had to learn
+     * dotted paths rather than skip them: a masked session that returned the real
+     * IP would be a function whose name is the only evidence it did anything.
+     */
+    /**
+     * Plaintext PII. **Opt-in and named** — for the security page that shows a
+     * user their own sessions, and for abuse investigation.
+     */
+    revealSession(doc) {
+        return revealPii(doc, this.piiFields);
+    }
+    /** As `revealSession`, for a list read. */
+    revealSessions(docs) {
+        return docs.map((d) => this.revealSession(d));
+    }
+    /**
+     * Masked PII — the default. `deviceInfo.ip` becomes a last-four mask, which
+     * is what every admin surface here actually needs: enough to tell two
+     * sessions apart, not enough to geolocate a person.
+     */
+    maskedSession(doc) {
+        return maskPii(doc, this.piiFields);
+    }
+    /** As `maskedSession`, for a list read. */
+    maskedSessions(docs) {
+        return docs.map((d) => this.maskedSession(d));
     }
     async list(model) {
         return this.sieveQuery(model, SessionRepository.SIEVE_FIELDS);
@@ -43,6 +70,8 @@ export class SessionRepository extends BaseRepository {
         const now = new Date();
         const expiresAt = new Date(now.getTime() + SESSION_EXPIRATION_MS);
         const sessionId = generateSessionId();
+        // Plain in, ciphertext out — the write hook encrypts the three nested
+        // `piiFields` paths below.
         const sessionData = {
             userId,
             deviceInfo: data.deviceInfo,
@@ -69,7 +98,19 @@ export class SessionRepository extends BaseRepository {
         // that supplies a location — the hot activity ping stays a single write.
         if (data?.location) {
             const current = await this.findById(sessionId); // mapDoc → already decrypted
-            updateData.location = { ...(current?.location ?? {}), ...data.location };
+            /*
+           * Merged off the REVEALED current session, not the stored one.
+           *
+           * `location.city` is one of this repository's three nested PII paths, so
+           * `current.location` holds ciphertext — spreading it into a plaintext
+           * patch would re-encrypt the city on the way down and make it
+           * permanently unreadable, the same defect as the payout crons.
+           */
+            const currentPlain = current ? this.revealSession(current) : null;
+            updateData.location = {
+                ...(currentPlain?.location ?? {}),
+                ...data.location,
+            };
         }
         try {
             await this.update(sessionId, updateData);

package/dist/features/auth/repository/token.repository.d.ts

@@ -1,6 +1,5 @@
-import type { DocumentSnapshot } from "../../../providers/db-firebase";
 import { BaseRepository } from "../../../providers/db-firebase";
-import { type EmailVerificationTokenDocument, type PasswordResetTokenDocument } from "../schemas";
+import { type EmailVerificationTokenDocument, type EmailVerificationTokenPlain, type PasswordResetTokenDocument, type PasswordResetTokenPlain } from "../schemas";
 export declare class EmailVerificationTokenRepository extends BaseRepository<EmailVerificationTokenDocument> {
     constructor();
     /**
@@ -19,7 +18,19 @@ export declare class EmailVerificationTokenRepository extends BaseRepository<Ema
      */
     protected piiFields: readonly ["email"];
     protected piiIndexMap: Record<string, string>;
-    protected mapDoc<D = EmailVerificationTokenDocument>(snap: DocumentSnapshot): D;
+    /** Plaintext PII. **Opt-in and named** — shows up in review and in a grep. */
+    revealToken(doc: EmailVerificationTokenDocument): EmailVerificationTokenPlain;
+    /** As `revealToken`, for a list read. */
+    revealTokens(docs: readonly EmailVerificationTokenDocument[]): EmailVerificationTokenPlain[];
+    /**
+     * Masked PII — **the default for any surface that only needs to identify a
+     * row to a human.** Decrypts first, then masks: the mask helpers refuse
+     * ciphertext by design, so passing a stored field straight in would return
+     * "Anonymous" for every row.
+     */
+    maskedToken(doc: EmailVerificationTokenDocument): EmailVerificationTokenPlain;
+    /** As `maskedToken`, for a list read. */
+    maskedTokens(docs: readonly EmailVerificationTokenDocument[]): EmailVerificationTokenPlain[];
     findByToken(token: string): Promise<EmailVerificationTokenDocument | null>;
     findByUserId(userId: string): Promise<EmailVerificationTokenDocument[]>;
     findByEmail(email: string): Promise<EmailVerificationTokenDocument[]>;
@@ -39,7 +50,19 @@ export declare class PasswordResetTokenRepository extends BaseRepository<Passwor
      */
     protected piiFields: readonly ["email"];
     protected piiIndexMap: Record<string, string>;
-    protected mapDoc<D = PasswordResetTokenDocument>(snap: DocumentSnapshot): D;
+    /** Plaintext PII. **Opt-in and named** — shows up in review and in a grep. */
+    revealResetToken(doc: PasswordResetTokenDocument): PasswordResetTokenPlain;
+    /** As `revealResetToken`, for a list read. */
+    revealResetTokens(docs: readonly PasswordResetTokenDocument[]): PasswordResetTokenPlain[];
+    /**
+     * Masked PII — **the default for any surface that only needs to identify a
+     * row to a human.** Decrypts first, then masks: the mask helpers refuse
+     * ciphertext by design, so passing a stored field straight in would return
+     * "Anonymous" for every row.
+     */
+    maskedResetToken(doc: PasswordResetTokenDocument): PasswordResetTokenPlain;
+    /** As `maskedResetToken`, for a list read. */
+    maskedResetTokens(docs: readonly PasswordResetTokenDocument[]): PasswordResetTokenPlain[];
     findByToken(token: string): Promise<PasswordResetTokenDocument | null>;
     findByUserId(userId: string): Promise<PasswordResetTokenDocument[]>;
     findByEmail(email: string): Promise<PasswordResetTokenDocument[]>;