@mohasinac/appkit 4.53.0 → 4.53.2

package/dist/next/routing/route-map.d.ts

@@ -50,6 +50,7 @@ export declare const DEFAULT_ROUTE_MAP: {
         readonly STORE_DIGITAL_CODES: (storeSlug: string) => string;
         readonly STORE_LIVE: (storeSlug: string) => string;
         readonly STORE_ART: (storeSlug: string) => string;
+        readonly STORE_SPARES: (storeSlug: string) => string;
         readonly CATEGORIES: "/categories";
         readonly CATEGORY_DETAIL: (slug: string) => string;
         readonly BRANDS: "/brands";
@@ -78,6 +79,19 @@ export declare const DEFAULT_ROUTE_MAP: {
         readonly COOKIE_POLICY: "/cookies";
         readonly REFUND_POLICY: "/refund-policy";
         readonly SHIPPING_POLICY: "/shipping-policy";
+        /**
+         * Cancellation policy. Distinct from the refund policy, which already
+         * covers cancellation in passing — PhonePe's merchant review asks for it
+         * by name, and so does the Consumer Protection (E-Commerce) Rules 2020
+         * disclosure list.
+         */
+        readonly CANCELLATION_POLICY: "/cancellation-policy";
+        /**
+         * Grievance officer. A MANDATORY published disclosure under the Consumer
+         * Protection (E-Commerce) Rules 2020 and the IT Rules 2021 — name,
+         * designation, contact and a response commitment.
+         */
+        readonly GRIEVANCE: "/grievance";
         readonly HOW_AUCTIONS_WORK: "/how-auctions-work";
         readonly HOW_PRE_ORDERS_WORK: "/how-pre-orders-work";
         readonly HOW_OFFERS_WORK: "/how-offers-work";
@@ -124,6 +138,7 @@ export declare const DEFAULT_ROUTE_MAP: {
         readonly LIVE: "/live";
         readonly LIVE_DETAIL: (slug: string) => string;
         readonly ART: "/art";
+        readonly SPARES: "/spares";
         readonly CATALOGUE_ITEM_DETAIL: (ownerSlug: string, itemId: string) => string;
     };
     readonly ERRORS: {
@@ -246,6 +261,9 @@ export declare const DEFAULT_ROUTE_MAP: {
         readonly STICKERS: "/store/stickers";
         readonly STICKERS_NEW: "/store/stickers/new";
         readonly STICKERS_EDIT: (id: string) => string;
+        readonly SPARES: "/store/spares";
+        readonly SPARES_NEW: "/store/spares/new";
+        readonly SPARES_EDIT: (id: string) => string;
         readonly PRINT_CENTER: "/store/print-center";
         readonly FULFILLMENT: "/store/fulfillment";
         readonly PAYOUT_METHODS: "/store/payout-methods";
@@ -324,6 +342,7 @@ export declare const DEFAULT_ROUTE_MAP: {
         readonly LIVE: "/admin/live";
         readonly ART: "/admin/art";
         readonly STICKERS: "/admin/stickers";
+        readonly SPARES: "/admin/spares";
         readonly GROUPED_LISTINGS: "/admin/grouped-listings";
         readonly GROUPED_LISTINGS_NEW: "/admin/grouped-listings/new";
         readonly GROUPED_LISTINGS_EDIT: (id: string) => string;
@@ -466,6 +485,7 @@ export declare const ROUTES: {
         readonly STORE_DIGITAL_CODES: (storeSlug: string) => string;
         readonly STORE_LIVE: (storeSlug: string) => string;
         readonly STORE_ART: (storeSlug: string) => string;
+        readonly STORE_SPARES: (storeSlug: string) => string;
         readonly CATEGORIES: "/categories";
         readonly CATEGORY_DETAIL: (slug: string) => string;
         readonly BRANDS: "/brands";
@@ -494,6 +514,19 @@ export declare const ROUTES: {
         readonly COOKIE_POLICY: "/cookies";
         readonly REFUND_POLICY: "/refund-policy";
         readonly SHIPPING_POLICY: "/shipping-policy";
+        /**
+         * Cancellation policy. Distinct from the refund policy, which already
+         * covers cancellation in passing — PhonePe's merchant review asks for it
+         * by name, and so does the Consumer Protection (E-Commerce) Rules 2020
+         * disclosure list.
+         */
+        readonly CANCELLATION_POLICY: "/cancellation-policy";
+        /**
+         * Grievance officer. A MANDATORY published disclosure under the Consumer
+         * Protection (E-Commerce) Rules 2020 and the IT Rules 2021 — name,
+         * designation, contact and a response commitment.
+         */
+        readonly GRIEVANCE: "/grievance";
         readonly HOW_AUCTIONS_WORK: "/how-auctions-work";
         readonly HOW_PRE_ORDERS_WORK: "/how-pre-orders-work";
         readonly HOW_OFFERS_WORK: "/how-offers-work";
@@ -540,6 +573,7 @@ export declare const ROUTES: {
         readonly LIVE: "/live";
         readonly LIVE_DETAIL: (slug: string) => string;
         readonly ART: "/art";
+        readonly SPARES: "/spares";
         readonly CATALOGUE_ITEM_DETAIL: (ownerSlug: string, itemId: string) => string;
     };
     readonly ERRORS: {
@@ -662,6 +696,9 @@ export declare const ROUTES: {
         readonly STICKERS: "/store/stickers";
         readonly STICKERS_NEW: "/store/stickers/new";
         readonly STICKERS_EDIT: (id: string) => string;
+        readonly SPARES: "/store/spares";
+        readonly SPARES_NEW: "/store/spares/new";
+        readonly SPARES_EDIT: (id: string) => string;
         readonly PRINT_CENTER: "/store/print-center";
         readonly FULFILLMENT: "/store/fulfillment";
         readonly PAYOUT_METHODS: "/store/payout-methods";
@@ -740,6 +777,7 @@ export declare const ROUTES: {
         readonly LIVE: "/admin/live";
         readonly ART: "/admin/art";
         readonly STICKERS: "/admin/stickers";
+        readonly SPARES: "/admin/spares";
         readonly GROUPED_LISTINGS: "/admin/grouped-listings";
         readonly GROUPED_LISTINGS_NEW: "/admin/grouped-listings/new";
         readonly GROUPED_LISTINGS_EDIT: (id: string) => string;
@@ -903,6 +941,9 @@ export declare const SELLER_ROUTES: {
     readonly STICKERS: "/store/stickers";
     readonly STICKERS_NEW: "/store/stickers/new";
     readonly STICKERS_EDIT: (id: string) => string;
+    readonly SPARES: "/store/spares";
+    readonly SPARES_NEW: "/store/spares/new";
+    readonly SPARES_EDIT: (id: string) => string;
     readonly PRINT_CENTER: "/store/print-center";
     readonly FULFILLMENT: "/store/fulfillment";
     readonly PAYOUT_METHODS: "/store/payout-methods";
@@ -931,6 +972,6 @@ export declare const SELLER_ROUTES: {
     readonly GUIDE_SETTINGS: "/store/guide/settings";
     readonly GUIDE_WHATSAPP: "/store/guide/whatsapp";
 };
-export declare const PUBLIC_ROUTES: readonly ["/", string, string, string, string, string, string, string, string, string, string, string, string, string, string, string, string, string, "/unauthorized", "/auth/login", "/auth/register", "/auth/forgot-password", "/auth/reset-password", "/auth/verify-email"];
+export declare const PUBLIC_ROUTES: readonly ["/", string, string, string, string, string, string, string, string, string, string, string, string, string, string, string, string, string, string, string, "/unauthorized", "/auth/login", "/auth/register", "/auth/forgot-password", "/auth/reset-password", "/auth/verify-email"];
 export declare const PROTECTED_ROUTES: readonly [string, string, string, string, string, string, string];
 export declare const AUTH_ROUTES: readonly ["/auth/login", "/auth/register"];

package/dist/next/routing/route-map.js

@@ -43,6 +43,13 @@ export const DEFAULT_ROUTE_MAP = {
         // `standard` — so the tab showed a real non-zero count and then landed on
         // a page containing none of those items.
         STORE_ART: (storeSlug) => `/stores/${storeSlug}/art`,
+        /*
+         * 🛑 `STORE_PAGE_TABS` is DERIVED from the plugin registry, so this tab
+         * appears the moment the plugin exists — and a missing
+         * `stores/[storeSlug]/spares/page.tsx` is then a clickable 404 that no
+         * audit covers. The folder lands in the same commit as this key.
+         */
+        STORE_SPARES: (storeSlug) => `/stores/${storeSlug}/spares`,
         CATEGORIES: "/categories",
         CATEGORY_DETAIL: (slug) => `/categories/${slug}`,
         BRANDS: "/brands",
@@ -86,6 +93,19 @@ export const DEFAULT_ROUTE_MAP = {
         COOKIE_POLICY: "/cookies",
         REFUND_POLICY: "/refund-policy",
         SHIPPING_POLICY: "/shipping-policy",
+        /**
+         * Cancellation policy. Distinct from the refund policy, which already
+         * covers cancellation in passing — PhonePe's merchant review asks for it
+         * by name, and so does the Consumer Protection (E-Commerce) Rules 2020
+         * disclosure list.
+         */
+        CANCELLATION_POLICY: "/cancellation-policy",
+        /**
+         * Grievance officer. A MANDATORY published disclosure under the Consumer
+         * Protection (E-Commerce) Rules 2020 and the IT Rules 2021 — name,
+         * designation, contact and a response commitment.
+         */
+        GRIEVANCE: "/grievance",
         HOW_AUCTIONS_WORK: "/how-auctions-work",
         HOW_PRE_ORDERS_WORK: "/how-pre-orders-work",
         HOW_OFFERS_WORK: "/how-offers-work",
@@ -188,6 +208,21 @@ export const DEFAULT_ROUTE_MAP = {
         // detail page stays PRODUCT_DETAIL (`/products/{slug}`), already wired in
         // `_internal/shared/listing-types/{art,stickers}/config.ts`.
         ART: "/art",
+        /*
+         * Part Two — loose components off disassembled items.
+         *
+         * 🛑 A REAL page, not a redirect shim like `/live`. Its plugin sets
+         * `inGeneralCatalogue: false`, and the rule for that flag is nav
+         * reachability: a type kept out of `/products` must own a page that
+         * `MAIN_NAV_ITEMS` links, or it is reachable from nowhere at all (Root
+         * Cause #61). A shim pointing back at `/products` would re-open exactly
+         * that hole while looking like it had closed it.
+         *
+         * Detail route stays `PRODUCT_DETAIL` — a spare checks out like any
+         * standard item, so it needs no bespoke detail page, same reasoning as
+         * art/stickers above.
+         */
+        SPARES: "/spares",
         // Personal catalogue (Feature B) — a user's own photo inventory of owned
         // items, distinct from marketplace listings. Public when the owner sets
         // an item's visibility to "public". The owner's full catalogue listing
@@ -319,6 +354,10 @@ export const DEFAULT_ROUTE_MAP = {
         STICKERS: "/store/stickers",
         STICKERS_NEW: "/store/stickers/new",
         STICKERS_EDIT: (id) => `/store/stickers/${id}/edit`,
+        // Part Two — spares
+        SPARES: "/store/spares",
+        SPARES_NEW: "/store/spares/new",
+        SPARES_EDIT: (id) => `/store/spares/${id}/edit`,
         PRINT_CENTER: "/store/print-center",
         FULFILLMENT: "/store/fulfillment",
         // S-STORE Tier — new extension routes
@@ -412,6 +451,8 @@ export const DEFAULT_ROUTE_MAP = {
         // EMI/art-stickers session — art / stickers
         ART: "/admin/art",
         STICKERS: "/admin/stickers",
+        // Part Two — spares
+        SPARES: "/admin/spares",
         GROUPED_LISTINGS: "/admin/grouped-listings",
         GROUPED_LISTINGS_NEW: "/admin/grouped-listings/new",
         GROUPED_LISTINGS_EDIT: (id) => `/admin/grouped-listings/${id}/edit`,
@@ -580,6 +621,10 @@ export const PUBLIC_ROUTES = [
     ROUTES.PUBLIC.PRIVACY,
     ROUTES.PUBLIC.ETHICS,
     ROUTES.PUBLIC.CODE_OF_CONDUCT,
+    ROUTES.PUBLIC.CANCELLATION_POLICY,
+    // Public by necessity: a grievance officer a complainant must sign in to
+    // find is not a published disclosure.
+    ROUTES.PUBLIC.GRIEVANCE,
     ROUTES.ERRORS.UNAUTHORIZED,
     ROUTES.AUTH.LOGIN,
     ROUTES.AUTH.REGISTER,

package/dist/providers/db-firebase/base.repository.d.ts

@@ -49,6 +49,28 @@ export declare abstract class BaseRepository<T extends DocumentData> {
      * text, so indexing an encrypted field would undo the encryption.
      */
     protected buildSearchTxtFor(_data: Record<string, JsonValue>): string[] | null;
+    /**
+     * Build this document's `*TokensIndex` fields — whole-word HMAC digests
+     * over PII, for admin search without decryption. Return `null` to leave
+     * the document alone (the default).
+     *
+     * Mirrors `buildSearchTxtFor`'s shape exactly, and for the reason that
+     * shape exists: a hook run from `applyWriteHooks` reaches EVERY write path
+     * — create, createWithId, update, the `*InTx`/`*InBatch` family, and a
+     * seed load, which goes through the same repository methods. A one-off
+     * backfill script cannot reach any of those; it only catches documents
+     * that already existed when it ran.
+     *
+     * 🛑 This is NOT `buildSearchTxtFor`'s inverse rule. `searchTxt` must never
+     * carry PII; this hook exists FOR PII, and runs in the only place that
+     * sees the plaintext before `encryptPiiFields` replaces it. See
+     * `security/blind-index-tokens.ts` for why the tokens are whole-word only.
+     *
+     * Return shape is `{ fieldName: digests[] }` rather than a single array,
+     * because a document can carry more than one token field (a payout has
+     * `sellerTokensIndex`, nothing else does yet, but the hook is general).
+     */
+    protected buildTokensIndexFor(_data: Record<string, JsonValue>): Record<string, string[]> | null;
     /**
      * The one place writes are transformed. Every write path routes through here
      * so a new method cannot silently skip encryption.

package/dist/providers/db-firebase/base.repository.js

@@ -5,6 +5,7 @@ import { applySieveToFirestore, countSieveMatches, } from "./sieve.js";
 import { deserializeTimestamps, prepareForFirestore } from "./helpers.js";
 import { getAdminDb } from "./admin.js";
 import { encryptPiiFields, piiIndicesFor } from "../../security/pii-encrypt.js";
+import { BLIND_INDEX_KEY_VERSION_FIELD, CURRENT_BLIND_INDEX_KEY_VERSION, } from "../../security/blind-index-tokens.js";
 /**
  * The underlying failure's message, for interpolation into a DatabaseError.
  *
@@ -133,6 +134,30 @@ export class BaseRepository {
     buildSearchTxtFor(_data) {
         return null;
     }
+    /**
+     * Build this document's `*TokensIndex` fields — whole-word HMAC digests
+     * over PII, for admin search without decryption. Return `null` to leave
+     * the document alone (the default).
+     *
+     * Mirrors `buildSearchTxtFor`'s shape exactly, and for the reason that
+     * shape exists: a hook run from `applyWriteHooks` reaches EVERY write path
+     * — create, createWithId, update, the `*InTx`/`*InBatch` family, and a
+     * seed load, which goes through the same repository methods. A one-off
+     * backfill script cannot reach any of those; it only catches documents
+     * that already existed when it ran.
+     *
+     * 🛑 This is NOT `buildSearchTxtFor`'s inverse rule. `searchTxt` must never
+     * carry PII; this hook exists FOR PII, and runs in the only place that
+     * sees the plaintext before `encryptPiiFields` replaces it. See
+     * `security/blind-index-tokens.ts` for why the tokens are whole-word only.
+     *
+     * Return shape is `{ fieldName: digests[] }` rather than a single array,
+     * because a document can carry more than one token field (a payout has
+     * `sellerTokensIndex`, nothing else does yet, but the hook is general).
+     */
+    buildTokensIndexFor(_data) {
+        return null;
+    }
     /**
      * The one place writes are transformed. Every write path routes through here
      * so a new method cannot silently skip encryption.
@@ -154,6 +179,17 @@ export class BaseRepository {
         const searchTxt = this.buildSearchTxtFor(out);
         if (searchTxt)
             out.searchTxt = searchTxt;
+        /*
+         * `data`, not `out` — the plaintext source, same as `piiIndicesFor`
+         * above. By this point `out` may already hold ciphertext, and hashing
+         * ciphertext would make the index meaningless.
+         */
+        const tokensIndex = this.buildTokensIndexFor(data);
+        if (tokensIndex) {
+            Object.assign(out, tokensIndex, {
+                [BLIND_INDEX_KEY_VERSION_FIELD]: CURRENT_BLIND_INDEX_KEY_VERSION,
+            });
+        }
         return out;
     }
     /**

package/dist/schemas/registry.d.ts

@@ -1011,6 +1011,8 @@ export declare const SCHEMAS: {
             brandWebsite: import("zod").ZodOptional<import("zod").ZodString>;
             brandCountry: import("zod").ZodOptional<import("zod").ZodString>;
             brandFounded: import("zod").ZodOptional<import("zod").ZodNumber>;
+            hasbroName: import("zod").ZodOptional<import("zod").ZodString>;
+            hasbroCoverImage: import("zod").ZodOptional<import("zod").ZodString>;
             highlights: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
             faqs: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodObject<{
                 question: import("zod").ZodString;
@@ -1604,6 +1606,8 @@ export declare const SCHEMAS: {
             brandWebsite?: string | undefined;
             brandCountry?: string | undefined;
             brandFounded?: number | undefined;
+            hasbroName?: string | undefined;
+            hasbroCoverImage?: string | undefined;
             highlights?: string[] | undefined;
             contentBody?: string | undefined;
             descriptionTemplates?: {
@@ -1775,6 +1779,8 @@ export declare const SCHEMAS: {
             brandWebsite?: string | undefined;
             brandCountry?: string | undefined;
             brandFounded?: number | undefined;
+            hasbroName?: string | undefined;
+            hasbroCoverImage?: string | undefined;
             highlights?: string[] | undefined;
             contentBody?: string | undefined;
             descriptionTemplates?: {
@@ -2605,12 +2611,12 @@ export declare const SCHEMAS: {
                 toDate: import("zod").ZodFunction<import("zod").ZodTuple<[], import("zod").ZodUnknown>, import("zod").ZodDate>;
             }, import("zod").ZodTypeAny, "passthrough">>]>;
             id: import("zod").ZodString;
-            type: import("zod").ZodEnum<["welcome", "carousel", "stats", "trust-indicators", "categories", "brands", "products", "pre-orders", "auctions", "banner", "features", "reviews", "whatsapp-community", "faq", "blog-articles", "newsletter", "stores", "events", "social-feed", "custom-cards", "google-reviews", "featured-bundles", "prize-draws", "event-raffles", "collection-cards"]>;
+            type: import("zod").ZodEnum<[import("..").SectionType, ...import("..").SectionType[]]>;
             order: import("zod").ZodNumber;
             enabled: import("zod").ZodBoolean;
             config: import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodType<import("./types").JsonValue, import("zod").ZodTypeDef, import("./types").JsonValue>>;
         }, "strip", import("zod").ZodTypeAny, {
-            type: "banner" | "stores" | "products" | "pre-orders" | "prize-draws" | "auctions" | "reviews" | "events" | "categories" | "brands" | "carousel" | "newsletter" | "features" | "stats" | "welcome" | "trust-indicators" | "whatsapp-community" | "faq" | "blog-articles" | "social-feed" | "custom-cards" | "google-reviews" | "featured-bundles" | "event-raffles" | "collection-cards";
+            type: import("..").SectionType;
             id: string;
             createdAt: string | Date | import("zod").objectOutputType<{
                 toDate: import("zod").ZodFunction<import("zod").ZodTuple<[], import("zod").ZodUnknown>, import("zod").ZodDate>;
@@ -2622,7 +2628,7 @@ export declare const SCHEMAS: {
             order: number;
             config: Record<string, import("./types").JsonValue>;
         }, {
-            type: "banner" | "stores" | "products" | "pre-orders" | "prize-draws" | "auctions" | "reviews" | "events" | "categories" | "brands" | "carousel" | "newsletter" | "features" | "stats" | "welcome" | "trust-indicators" | "whatsapp-community" | "faq" | "blog-articles" | "social-feed" | "custom-cards" | "google-reviews" | "featured-bundles" | "event-raffles" | "collection-cards";
+            type: import("..").SectionType;
             id: string;
             createdAt: string | Date | import("zod").objectInputType<{
                 toDate: import("zod").ZodFunction<import("zod").ZodTuple<[], import("zod").ZodUnknown>, import("zod").ZodDate>;
@@ -5501,18 +5507,21 @@ export declare const SCHEMAS: {
             audienceUserIds?: string[] | undefined;
         }>;
         readonly homepageSection: import("zod").ZodObject<{
-            type: import("zod").ZodEnum<["welcome", "carousel", "stats", "trust-indicators", "categories", "brands", "products", "pre-orders", "auctions", "banner", "features", "reviews", "whatsapp-community", "faq", "blog-articles", "newsletter", "stores", "events", "social-feed", "custom-cards", "google-reviews", "featured-bundles", "prize-draws", "event-raffles", "collection-cards"]>;
+            type: import("zod").ZodEnum<[import("..").SectionType, ...import("..").SectionType[]]>;
             enabled: import("zod").ZodDefault<import("zod").ZodOptional<import("zod").ZodBoolean>>;
             order: import("zod").ZodOptional<import("zod").ZodNumber>;
+            surface: import("zod").ZodOptional<import("zod").ZodEnum<["homepage", "category", "brand", "product", "store"]>>;
             config: import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodType<import("./types").JsonValue, import("zod").ZodTypeDef, import("./types").JsonValue>>;
         }, "strip", import("zod").ZodTypeAny, {
-            type: "banner" | "stores" | "products" | "pre-orders" | "prize-draws" | "auctions" | "reviews" | "events" | "categories" | "brands" | "carousel" | "newsletter" | "features" | "stats" | "welcome" | "trust-indicators" | "whatsapp-community" | "faq" | "blog-articles" | "social-feed" | "custom-cards" | "google-reviews" | "featured-bundles" | "event-raffles" | "collection-cards";
+            type: import("..").SectionType;
             enabled: boolean;
             config: Record<string, import("./types").JsonValue>;
+            surface?: "brand" | "category" | "store" | "product" | "homepage" | undefined;
             order?: number | undefined;
         }, {
-            type: "banner" | "stores" | "products" | "pre-orders" | "prize-draws" | "auctions" | "reviews" | "events" | "categories" | "brands" | "carousel" | "newsletter" | "features" | "stats" | "welcome" | "trust-indicators" | "whatsapp-community" | "faq" | "blog-articles" | "social-feed" | "custom-cards" | "google-reviews" | "featured-bundles" | "event-raffles" | "collection-cards";
+            type: import("..").SectionType;
             config: Record<string, import("./types").JsonValue>;
+            surface?: "brand" | "category" | "store" | "product" | "homepage" | undefined;
             enabled?: boolean | undefined;
             order?: number | undefined;
         }>;

package/dist/security/blind-index-tokens.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The shortest token worth indexing.
+ *
+ * 🛑 Three, matching the frequency argument in the header. Two-character
+ * tokens are both uninformative as a search ("find everyone with 'li' in
+ * their name") and the regime where counting starts to work.
+ */
+export declare const BLIND_INDEX_MIN_TOKEN = 3;
+/** Tokens per field. A bound, so one pathological value cannot bloat a document. */
+export declare const BLIND_INDEX_MAX_TOKENS = 24;
+/** Split a value into whole, normalised, long-enough words. */
+export declare function tokensOf(value: string): string[];
+/**
+ * Build a `*TokensIndex` from one or more plaintext values.
+ *
+ * Returns `[]` rather than undefined for an empty input, so the field is
+ * always present and `array-contains` behaves predictably. An ABSENT array
+ * field and an empty one are the same to `array-contains`, but they are not
+ * the same to a human reading the document and wondering whether the
+ * backfill ran.
+ */
+export declare function buildTokensIndex(...values: readonly (string | null | undefined)[]): string[];
+/**
+ * The digest to pass to `array-contains` for one search term.
+ *
+ * Returns null when the term is too short to have been indexed — the caller
+ * must then return NOTHING rather than fall back to an unfiltered query.
+ * A two-character admin search that quietly listed every user would be the
+ * `plan.empty` bug (a query that normalises away matching everything) on
+ * the one surface where the result set is people.
+ */
+export declare function tokensIndexQueryValue(term: string): string | null;
+/**
+ * Which key version wrote a given index.
+ *
+ * 🛑 Rotating `PII_HMAC_KEY` invalidates every digest written before it, and
+ * the failure is silent: searches simply stop matching, which reads as "no
+ * such user" rather than as a broken index. Recording the version means a
+ * backfill can tell what it still has to rewrite instead of rewriting
+ * everything, and a mismatch is detectable rather than invisible.
+ */
+export declare const BLIND_INDEX_KEY_VERSION_FIELD = "blindIndexKeyVersion";
+/**
+ * The version every NEW write stamps. Bump by hand when `PII_HMAC_KEY`
+ * rotates — never computed, because a value derived from the key itself
+ * would be constant across every rotation and the whole point is to tell
+ * two rotations apart.
+ *
+ * Read from `PII_HMAC_KEY_VERSION` so the repository write path (which runs
+ * inside the Next.js/Functions runtime) and `backfill-blind-index.mjs`
+ * (which runs as a standalone script before `appkit/dist` is necessarily
+ * current) agree without importing from each other.
+ */
+export declare const CURRENT_BLIND_INDEX_KEY_VERSION: number;

package/dist/security/blind-index-tokens.js

@@ -0,0 +1,152 @@
+/*
+ * WHY: An admin needs to find a person by name without anything on the
+ *      server being able to read that name, and without the index itself
+ *      becoming the leak.
+ * WHAT: `*TokensIndex` — a whole-word HMAC token array, and the ONE
+ *       normaliser both sides must use.
+ *
+ * ## 🛑 WHOLE WORDS ONLY, 3 characters minimum. This is the security
+ *    boundary, not a tuning preference.
+ *
+ * The edge-n-gram expansion that makes `searchTxt` good is exactly what
+ * would make a blind index leak. An attacker with read access cannot
+ * compute HMACs without the key — but they can COUNT them. A 1-character
+ * prefix has 36 possible hashes and a 2-character one roughly 1,300, so the
+ * most frequent hash in the column is `a`, the second is `e`, and the
+ * distribution unpicks from there by ordinary frequency analysis. Whole
+ * tokens keep the space uninteresting, and "type a full first or last name"
+ * is what admin people-search actually needs.
+ *
+ * So: never call `buildSearchTxt` to build one of these, never add a prefix
+ * loop, and never derive one field from the other. `audit-blind-index-tokens`
+ * R1 blocks all three.
+ *
+ * ## 🛑 `hmacBlindIndex` does NOT normalise — it hashes the raw string
+ *
+ * `Mohasin` and `mohasin` therefore produce different digests. Both sides
+ * must run the same normaliser BEFORE hashing, and if they ever diverge a
+ * backfill does not fix it: you must first discover the divergence, and the
+ * symptom is "search returns nothing", which reads as "no such user".
+ *
+ * That is why `buildTokensIndex` and `tokensIndexQueryValue` live in one
+ * file and share `normaliseToken` — the write side and the query side
+ * cannot be edited independently.
+ *
+ * ## Why this is a DIFFERENT field from `searchTxt`, not an extension
+ *
+ * Different properties, deliberately: hashed not plaintext, whole-word not
+ * prefix-expanded, admin-only not public. `searchTxt` still never carries
+ * PII, and that rule is untouched. Keeping them visibly distinct is what
+ * stops someone "simplifying" one into the other.
+ *
+ * @tag domain:security
+ * @tag layer:shared
+ * @tag pattern:none
+ * @tag access:server
+ * @tag consumers:UserRepository,PayoutRepository,AddressesRepository,backfill-blind-index
+ * @tag sideEffects:none
+ */
+import { hmacBlindIndex } from "./pii-encrypt.js";
+/**
+ * The shortest token worth indexing.
+ *
+ * 🛑 Three, matching the frequency argument in the header. Two-character
+ * tokens are both uninformative as a search ("find everyone with 'li' in
+ * their name") and the regime where counting starts to work.
+ */
+export const BLIND_INDEX_MIN_TOKEN = 3;
+/** Tokens per field. A bound, so one pathological value cannot bloat a document. */
+export const BLIND_INDEX_MAX_TOKENS = 24;
+/**
+ * The ONE normaliser for this path.
+ *
+ * Deliberately NOT `normalizeSearchText`: that one exists to make the
+ * public write path and the Firestore token query agree, and it is tuned
+ * for product titles. Reusing it here would couple two schemes that must be
+ * able to change independently — and a change made for search reasons would
+ * silently invalidate every stored digest.
+ *
+ * Lower-case, strip diacritics, drop everything that is not a letter or a
+ * digit. An email is split on its punctuation too, so `mohsin0502@gmail.com`
+ * yields `mohsin0502`, `gmail`, `com` — the local part being the useful one.
+ */
+function normaliseToken(raw) {
+    return raw
+        .normalize("NFD")
+        .replace(/[̀-ͯ]/g, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]/g, "");
+}
+/** Split a value into whole, normalised, long-enough words. */
+export function tokensOf(value) {
+    const out = [];
+    const seen = new Set();
+    for (const part of value.split(/[\s.@_\-+/\\,;:()[\]]+/)) {
+        const t = normaliseToken(part);
+        if (t.length < BLIND_INDEX_MIN_TOKEN)
+            continue;
+        if (seen.has(t))
+            continue;
+        seen.add(t);
+        out.push(t);
+        if (out.length >= BLIND_INDEX_MAX_TOKENS)
+            break;
+    }
+    return out;
+}
+/**
+ * Build a `*TokensIndex` from one or more plaintext values.
+ *
+ * Returns `[]` rather than undefined for an empty input, so the field is
+ * always present and `array-contains` behaves predictably. An ABSENT array
+ * field and an empty one are the same to `array-contains`, but they are not
+ * the same to a human reading the document and wondering whether the
+ * backfill ran.
+ */
+export function buildTokensIndex(...values) {
+    const tokens = new Set();
+    for (const v of values) {
+        if (!v)
+            continue;
+        for (const t of tokensOf(v))
+            tokens.add(t);
+    }
+    return [...tokens].slice(0, BLIND_INDEX_MAX_TOKENS).map((t) => hmacBlindIndex(t));
+}
+/**
+ * The digest to pass to `array-contains` for one search term.
+ *
+ * Returns null when the term is too short to have been indexed — the caller
+ * must then return NOTHING rather than fall back to an unfiltered query.
+ * A two-character admin search that quietly listed every user would be the
+ * `plan.empty` bug (a query that normalises away matching everything) on
+ * the one surface where the result set is people.
+ */
+export function tokensIndexQueryValue(term) {
+    const t = normaliseToken(term);
+    if (t.length < BLIND_INDEX_MIN_TOKEN)
+        return null;
+    return hmacBlindIndex(t);
+}
+/**
+ * Which key version wrote a given index.
+ *
+ * 🛑 Rotating `PII_HMAC_KEY` invalidates every digest written before it, and
+ * the failure is silent: searches simply stop matching, which reads as "no
+ * such user" rather than as a broken index. Recording the version means a
+ * backfill can tell what it still has to rewrite instead of rewriting
+ * everything, and a mismatch is detectable rather than invisible.
+ */
+export const BLIND_INDEX_KEY_VERSION_FIELD = "blindIndexKeyVersion";
+/**
+ * The version every NEW write stamps. Bump by hand when `PII_HMAC_KEY`
+ * rotates — never computed, because a value derived from the key itself
+ * would be constant across every rotation and the whole point is to tell
+ * two rotations apart.
+ *
+ * Read from `PII_HMAC_KEY_VERSION` so the repository write path (which runs
+ * inside the Next.js/Functions runtime) and `backfill-blind-index.mjs`
+ * (which runs as a standalone script before `appkit/dist` is necessarily
+ * current) agree without importing from each other.
+ */
+export const CURRENT_BLIND_INDEX_KEY_VERSION = Number((typeof process !== "undefined" ? process.env?.PII_HMAC_KEY_VERSION : undefined) ?? "1");

package/dist/security/index.d.ts

@@ -10,4 +10,4 @@ export { encryptValue, decryptValue, hmacBlindIndex, encryptPiiFields, decryptPi
 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";
+export { encryptSecret, decryptSecret, isSecretEncrypted, maskSecret, encryptBuffer, decryptBuffer, isBufferEncrypted, } from "./settings-encryption";

package/dist/security/index.js

@@ -22,7 +22,7 @@ export { revealPii, maskPii, revealPiiAll, maskPiiAll } from "./pii-accessors.js
 // universal client+server index.ts. See pii-mask.ts's header comment.
 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";
+export { encryptSecret, decryptSecret, isSecretEncrypted, maskSecret, encryptBuffer, decryptBuffer, isBufferEncrypted, } from "./settings-encryption.js";
 // RBAC system — DELETED 2026-08-29.
 //
 // `security/rbac/**` was a complete second permission system: DEFAULT_ROLES,

package/dist/security/settings-encryption.d.ts

@@ -1,4 +1,39 @@
 export declare function encryptSecret(plaintext: string): string;
 export declare function decryptSecret(encrypted: string): string;
 export declare function isSecretEncrypted(value: string): boolean;
+/**
+ * AES-256-GCM a file's bytes under `SETTINGS_ENCRYPTION_KEY`.
+ *
+ * Throws when the key is unset — deliberately, and identically to
+ * `encryptSecret`. A document store that silently writes plaintext when
+ * misconfigured is worse than one that refuses, because nothing downstream can
+ * tell the two apart afterwards.
+ */
+export declare function encryptBuffer(plaintext: Buffer): Buffer;
+/**
+ * Reverse `encryptBuffer`.
+ *
+ * 🛑 Unlike `decryptSecret`, a buffer with no `enc:v1:` prefix is REJECTED
+ * rather than passed through. That asymmetry is intentional. `decryptSecret`
+ * tolerates plaintext because the settings collection genuinely holds
+ * unencrypted placeholders that predate encryption, so passing them through is
+ * the migration path. Here there is no such legacy: every object this reads was
+ * written by `encryptBuffer`, so an unprefixed buffer means the wrong object,
+ * a truncated download, or an upload that bypassed encryption — and returning
+ * it verbatim would serve one of those to an admin as though it were fine.
+ *
+ * GCM authentication also means `final()` throws on any tampering or on the
+ * wrong key, so a corrupted object fails loudly instead of yielding garbage.
+ */
+export declare function decryptBuffer(encrypted: Buffer): Buffer;
+/**
+ * True when `buf` carries the binary envelope AND is long enough to hold a
+ * complete one.
+ *
+ * The length check is not pedantry: without it a 7-byte buffer containing only
+ * the prefix passes, and `decryptBuffer` then hands `createDecipheriv` a
+ * zero-length IV, which throws `Invalid initialization vector` — an error that
+ * describes the crypto call rather than the truncated download that caused it.
+ */
+export declare function isBufferEncrypted(buf: Buffer): boolean;
 export declare function maskSecret(value: string): string;