@mohasinac/appkit 4.52.5 → 4.53.1

package/dist/react/hooks/useEntityDelete.js

@@ -1,7 +1,11 @@
 "use client";
 import { normalizeError } from "../../errors/normalize.js";
 import { useState, useCallback } from "react";
-import { useToast } from "../../ui/index.js";
+// Defining modules, not the sibling barrel — Root Cause #18. `ui/index.ts` and
+// `react/index.ts` re-exported into each other, which is the whole of
+// `audit-import-cycles` component 1: an 18-module knot held together entirely
+// by barrel hops, none of which needed the barrel.
+import { useToast } from "../../ui/components/toast-context.js";
 export function useEntityDelete(opts) {
     const [deletingId, setDeletingId] = useState(null);
     const { showToast } = useToast();

package/dist/react/hooks/useMessage.js

@@ -10,7 +10,11 @@
  * inline (e.g. reviews, settings views).
  */
 import { useState, useCallback, useRef, useEffect } from "react";
-import { useToast } from "../../ui/index.js";
+// Defining modules, not the sibling barrel — Root Cause #18. `ui/index.ts` and
+// `react/index.ts` re-exported into each other, which is the whole of
+// `audit-import-cycles` component 1: an 18-module knot held together entirely
+// by barrel hops, none of which needed the barrel.
+import { useToast } from "../../ui/components/toast-context.js";
 export function useMessage() {
     const { showToast } = useToast();
     const [message, setMessage] = useState(null);

package/dist/repositories/index.d.ts

@@ -5,8 +5,8 @@
  * Server-only — all repository instances use firebase-admin.
  */
 export { BaseRepository } from "../providers/db-firebase";
-export { unitOfWork } from "../core";
-export type { UnitOfWork } from "../core";
+export { unitOfWork } from "../core/unit-of-work";
+export type { UnitOfWork } from "../core/unit-of-work";
 export { UserRepository, userRepository, EmailVerificationTokenRepository, PasswordResetTokenRepository, emailVerificationTokenRepository, passwordResetTokenRepository, tokenRepository, SessionRepository, sessionRepository, } from "../features/auth/repository";
 export { SmsCounterRepository, smsCounterRepository, } from "../features/auth/repository/sms-counter.repository";
 export { AddressesRepository, addressesRepository, } from "../features/addresses";

package/dist/repositories/index.js

@@ -7,7 +7,12 @@
 // Shared repository foundations
 export { BaseRepository } from "../providers/db-firebase/index.js";
 // Unit of Work - atomic multi-collection operations
-export { unitOfWork } from "../core/index.js";
+/*
+ * Deep, not `../core`: that barrel pulls in every core module, several of which
+ * import repositories back out of this file. One barrel re-exporting another
+ * barrel is how component 2's cycle stayed closed.
+ */
+export { unitOfWork } from "../core/unit-of-work.js";
 // Core repositories
 export { UserRepository, userRepository, EmailVerificationTokenRepository, PasswordResetTokenRepository, emailVerificationTokenRepository, passwordResetTokenRepository, tokenRepository, SessionRepository, sessionRepository, } from "../features/auth/repository/index.js";
 export { SmsCounterRepository, smsCounterRepository, } from "../features/auth/repository/sms-counter.repository.js";

package/dist/schemas/registry.d.ts

@@ -502,15 +502,15 @@ export declare const SCHEMAS: {
                 }, "strip", import("zod").ZodTypeAny, {
                     title?: string | undefined;
                     description?: string | undefined;
-                    textAlign?: "center" | "left" | "right" | undefined;
                     textColor?: string | undefined;
+                    textAlign?: "center" | "left" | "right" | undefined;
                     subtitle?: string | undefined;
                     eyebrow?: string | undefined;
                 }, {
                     title?: string | undefined;
                     description?: string | undefined;
-                    textAlign?: "center" | "left" | "right" | undefined;
                     textColor?: string | undefined;
+                    textAlign?: "center" | "left" | "right" | undefined;
                     subtitle?: string | undefined;
                     eyebrow?: string | undefined;
                 }>>;
@@ -569,8 +569,8 @@ export declare const SCHEMAS: {
                 content?: {
                     title?: string | undefined;
                     description?: string | undefined;
-                    textAlign?: "center" | "left" | "right" | undefined;
                     textColor?: string | undefined;
+                    textAlign?: "center" | "left" | "right" | undefined;
                     subtitle?: string | undefined;
                     eyebrow?: string | undefined;
                 } | undefined;
@@ -610,8 +610,8 @@ export declare const SCHEMAS: {
                 content?: {
                     title?: string | undefined;
                     description?: string | undefined;
-                    textAlign?: "center" | "left" | "right" | undefined;
                     textColor?: string | undefined;
+                    textAlign?: "center" | "left" | "right" | undefined;
                     subtitle?: string | undefined;
                     eyebrow?: string | undefined;
                 } | undefined;
@@ -749,8 +749,8 @@ export declare const SCHEMAS: {
                 content?: {
                     title?: string | undefined;
                     description?: string | undefined;
-                    textAlign?: "center" | "left" | "right" | undefined;
                     textColor?: string | undefined;
+                    textAlign?: "center" | "left" | "right" | undefined;
                     subtitle?: string | undefined;
                     eyebrow?: string | undefined;
                 } | undefined;
@@ -858,8 +858,8 @@ export declare const SCHEMAS: {
                 content?: {
                     title?: string | undefined;
                     description?: string | undefined;
-                    textAlign?: "center" | "left" | "right" | undefined;
                     textColor?: string | undefined;
+                    textAlign?: "center" | "left" | "right" | undefined;
                     subtitle?: string | undefined;
                     eyebrow?: string | undefined;
                 } | undefined;
@@ -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>;
@@ -2796,10 +2802,10 @@ export declare const SCHEMAS: {
                     toDate: import("zod").ZodFunction<import("zod").ZodTuple<[], import("zod").ZodUnknown>, import("zod").ZodDate>;
                 }, import("zod").ZodTypeAny, "passthrough">;
                 transactionId?: string | undefined;
+                proofUrl?: string | undefined;
                 paidAt?: string | Date | import("zod").objectOutputType<{
                     toDate: import("zod").ZodFunction<import("zod").ZodTuple<[], import("zod").ZodUnknown>, import("zod").ZodDate>;
                 }, import("zod").ZodTypeAny, "passthrough"> | undefined;
-                proofUrl?: string | undefined;
                 reminderSentAt?: string | Date | import("zod").objectOutputType<{
                     toDate: import("zod").ZodFunction<import("zod").ZodTuple<[], import("zod").ZodUnknown>, import("zod").ZodDate>;
                 }, import("zod").ZodTypeAny, "passthrough"> | undefined;
@@ -2811,10 +2817,10 @@ export declare const SCHEMAS: {
                     toDate: import("zod").ZodFunction<import("zod").ZodTuple<[], import("zod").ZodUnknown>, import("zod").ZodDate>;
                 }, import("zod").ZodTypeAny, "passthrough">;
                 transactionId?: string | undefined;
+                proofUrl?: string | undefined;
                 paidAt?: string | Date | import("zod").objectInputType<{
                     toDate: import("zod").ZodFunction<import("zod").ZodTuple<[], import("zod").ZodUnknown>, import("zod").ZodDate>;
                 }, import("zod").ZodTypeAny, "passthrough"> | undefined;
-                proofUrl?: string | undefined;
                 reminderSentAt?: string | Date | import("zod").objectInputType<{
                     toDate: import("zod").ZodFunction<import("zod").ZodTuple<[], import("zod").ZodUnknown>, import("zod").ZodDate>;
                 }, import("zod").ZodTypeAny, "passthrough"> | undefined;
@@ -3056,10 +3062,10 @@ export declare const SCHEMAS: {
                     toDate: import("zod").ZodFunction<import("zod").ZodTuple<[], import("zod").ZodUnknown>, import("zod").ZodDate>;
                 }, import("zod").ZodTypeAny, "passthrough">;
                 transactionId?: string | undefined;
+                proofUrl?: string | undefined;
                 paidAt?: string | Date | import("zod").objectOutputType<{
                     toDate: import("zod").ZodFunction<import("zod").ZodTuple<[], import("zod").ZodUnknown>, import("zod").ZodDate>;
                 }, import("zod").ZodTypeAny, "passthrough"> | undefined;
-                proofUrl?: string | undefined;
                 reminderSentAt?: string | Date | import("zod").objectOutputType<{
                     toDate: import("zod").ZodFunction<import("zod").ZodTuple<[], import("zod").ZodUnknown>, import("zod").ZodDate>;
                 }, import("zod").ZodTypeAny, "passthrough"> | undefined;
@@ -3204,10 +3210,10 @@ export declare const SCHEMAS: {
                     toDate: import("zod").ZodFunction<import("zod").ZodTuple<[], import("zod").ZodUnknown>, import("zod").ZodDate>;
                 }, import("zod").ZodTypeAny, "passthrough">;
                 transactionId?: string | undefined;
+                proofUrl?: string | undefined;
                 paidAt?: string | Date | import("zod").objectInputType<{
                     toDate: import("zod").ZodFunction<import("zod").ZodTuple<[], import("zod").ZodUnknown>, import("zod").ZodDate>;
                 }, import("zod").ZodTypeAny, "passthrough"> | undefined;
-                proofUrl?: string | undefined;
                 reminderSentAt?: string | Date | import("zod").objectInputType<{
                     toDate: import("zod").ZodFunction<import("zod").ZodTuple<[], import("zod").ZodUnknown>, import("zod").ZodDate>;
                 }, import("zod").ZodTypeAny, "passthrough"> | undefined;
@@ -4616,14 +4622,7 @@ export declare const SCHEMAS: {
             internalNotes?: string | undefined;
         }>;
     };
-    readonly api: {
-        readonly "POST /api/wishlist": import("./types").ApiRouteSchema<import("zod").ZodTypeAny, import("zod").ZodTypeAny, import("zod").ZodTypeAny, import("zod").ZodTypeAny>;
-        readonly "POST /api/auth/session": import("./types").ApiRouteSchema<import("zod").ZodTypeAny, import("zod").ZodTypeAny, import("zod").ZodTypeAny, import("zod").ZodTypeAny>;
-        readonly "POST /api/admin/products/[id]/group": import("./types").ApiRouteSchema<import("zod").ZodTypeAny, import("zod").ZodTypeAny, import("zod").ZodTypeAny, import("zod").ZodTypeAny>;
-        readonly "POST /api/media/sign": import("./types").ApiRouteSchema<import("zod").ZodTypeAny, import("zod").ZodTypeAny, import("zod").ZodTypeAny, import("zod").ZodTypeAny>;
-        readonly "POST /api/media/finalize": import("./types").ApiRouteSchema<import("zod").ZodTypeAny, import("zod").ZodTypeAny, import("zod").ZodTypeAny, import("zod").ZodTypeAny>;
-        readonly "GET /api/search/suggestions": import("./types").ApiRouteSchema<import("zod").ZodTypeAny, import("zod").ZodTypeAny, import("zod").ZodTypeAny, import("zod").ZodTypeAny>;
-    };
+    readonly api: {};
     readonly forms: {
         readonly product: import("zod").ZodObject<{
             title: import("zod").ZodOptional<import("zod").ZodString>;
@@ -5508,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;
         }>;
@@ -6354,8 +6356,8 @@ export declare const SCHEMAS: {
                 kind: import("zod").ZodOptional<import("zod").ZodString>;
             }, "strip", import("zod").ZodTypeAny, {
                 refreshToken: string;
-                idToken: string;
                 localId: string;
+                idToken: string;
                 expiresIn: string;
                 email?: string | undefined;
                 kind?: string | undefined;
@@ -6372,8 +6374,8 @@ export declare const SCHEMAS: {
                 rawUserInfo?: string | undefined;
             }, {
                 refreshToken: string;
-                idToken: string;
                 localId: string;
+                idToken: string;
                 expiresIn: string;
                 email?: string | undefined;
                 kind?: string | undefined;

package/dist/schemas/registry.js

@@ -75,20 +75,37 @@ const firestore = {
     // those are touched in W5/W7.
 };
 // ---------------------------------------------------------------------------
-// API route schemas — W4 seed cohort. Each entry maps an HTTP-verb-and-path
-// key to its `{ body?, query?, params?, response? }` schema bundle. The
-// `createRouteHandler` helper accepts either a direct Zod schema or one of
-// these keys.
-// ---------------------------------------------------------------------------
-import { postApiWishlist, postApiAuthSession, postApiAdminProductsIdGroup, postApiMediaSign, postApiMediaFinalize, getApiSearchSuggestions, } from "./api-routes.js";
-const api = {
-    "POST /api/wishlist": postApiWishlist,
-    "POST /api/auth/session": postApiAuthSession,
-    "POST /api/admin/products/[id]/group": postApiAdminProductsIdGroup,
-    "POST /api/media/sign": postApiMediaSign,
-    "POST /api/media/finalize": postApiMediaFinalize,
-    "GET /api/search/suggestions": getApiSearchSuggestions,
-};
+// API route schemas — see the `api` bucket below.
+/*
+ * 🛑 EMPTY, deliberately, as of 2026-10-17 — and `audit-route-schema-registry`
+ * is retired with it.
+ *
+ * This bucket is an ADDRESSING convenience: it lets a route write
+ * `schema: "POST /api/wishlist"` instead of importing the schema. Measured
+ * before emptying it: 6 keys registered, **0 routes passing a key string**,
+ * and 170 route files passing a schema identifier directly. So nothing has
+ * ever read it by key.
+ *
+ * The audit that policed it reported "576 of 582 routes await registration",
+ * which reads as a migration backlog and is not one. Its own header said so:
+ * *"not a migration backlog winding down, it is a registry almost nothing
+ * uses"*. And the codebase had already chosen the other convention — when
+ * `postApiWishlist` was found declared here while `/api/wishlist` read its
+ * body raw, the fix was to re-export the schema for DIRECT use at the route,
+ * not to adopt the key form.
+ *
+ * The safety property — a handler that reads a body must validate it — is
+ * owned by `audit-unvalidated-request-body`, which is strict-zero and at 0.
+ * Widening THAT rule to see `export async function POST` (it had only matched
+ * `export const POST`) found two genuinely unvalidated bodies on the session
+ * endpoints. That is what 576 registry keys would not have found.
+ *
+ * The bucket stays declared because `audit-schema-registry-completeness`
+ * requires every bucket to exist, and because the registry's own doctrine is
+ * that an empty bucket is honest while a bucket of placeholders "reads as
+ * migrated to everyone who comes after".
+ */
+const api = {};
 // ---------------------------------------------------------------------------
 // Form schemas — keyed by form id (matches FormShell/QuickFormDrawer `formId`).
 // `audit-form-schema` already enforces presence at FormShell sites; this

package/dist/schemas/webhooks/google-oauth.d.ts

@@ -19,8 +19,8 @@ export declare const googleSignInWithIdpResponseSchema: z.ZodObject<{
     kind: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     refreshToken: string;
-    idToken: string;
     localId: string;
+    idToken: string;
     expiresIn: string;
     email?: string | undefined;
     kind?: string | undefined;
@@ -37,8 +37,8 @@ export declare const googleSignInWithIdpResponseSchema: z.ZodObject<{
     rawUserInfo?: string | undefined;
 }, {
     refreshToken: string;
-    idToken: string;
     localId: string;
+    idToken: string;
     expiresIn: string;
     email?: string | undefined;
     kind?: string | 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");