@mohasinac/appkit 4.52.5 → 4.53.0

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

@@ -1,3 +1,4 @@
+import type { Plaintext } from "../../security/encrypted";
 import type { FirestoreDocument } from "@mohasinac/appkit";
 import type { CollectionReference, DocumentData, DocumentReference, DocumentSnapshot, Firestore, Query, Transaction, WriteBatch } from "firebase-admin/firestore";
 import { type FirebaseSieveFields, type FirebaseSieveOptions, type FirebaseSieveResult, type SieveModel } from "./sieve";
@@ -111,7 +112,7 @@ export declare abstract class BaseRepository<T extends DocumentData> {
         doc: T | null | undefined;
         patch: Partial<T>;
     }>): Promise<number>;
-    create(data: Partial<T> | FirestoreDocument): Promise<T>;
+    create(data: Partial<Plaintext<T>> | FirestoreDocument): Promise<T>;
     /**
      * Write a document at a CALLER-CHOSEN id.
      *
@@ -143,8 +144,9 @@ export declare abstract class BaseRepository<T extends DocumentData> {
      * NAME: `createWithId` reads as "create" and behaves as "replace", and that
      * gap is what made the wrong conclusion so easy to reach.
      */
-    createWithId(id: string, data: Partial<T>): Promise<T>;
-    update(id: string, data: Partial<T>): Promise<T>;
+    createWithId(id: string, data: Partial<Plaintext<T>>): Promise<T>;
+    /** Accepts the PLAINTEXT shape — see `create` for why. */
+    update(id: string, data: Partial<Plaintext<T>>): Promise<T>;
     delete(id: string): Promise<void>;
     exists(id: string): Promise<boolean>;
     /**
@@ -195,12 +197,12 @@ export declare abstract class BaseRepository<T extends DocumentData> {
     }): Promise<Record<string, number | undefined>>;
     findByIdInTx(tx: Transaction, id: string): Promise<T | null>;
     findByIdOrFailInTx(tx: Transaction, id: string): Promise<T>;
-    createInTx(tx: Transaction, data: Partial<T> | FirestoreDocument): DocumentReference;
-    createWithIdInTx(tx: Transaction, id: string, data: Partial<T> | FirestoreDocument): DocumentReference;
-    updateInTx(tx: Transaction, id: string, data: Partial<T>): void;
+    createInTx(tx: Transaction, data: Partial<Plaintext<T>> | FirestoreDocument): DocumentReference;
+    createWithIdInTx(tx: Transaction, id: string, data: Partial<Plaintext<T>> | FirestoreDocument): DocumentReference;
+    updateInTx(tx: Transaction, id: string, data: Partial<Plaintext<T>>): void;
     deleteInTx(tx: Transaction, id: string): void;
-    createInBatch(batch: WriteBatch, data: Partial<T> | FirestoreDocument): DocumentReference;
-    createWithIdInBatch(batch: WriteBatch, id: string, data: Partial<T> | FirestoreDocument): void;
-    updateInBatch(batch: WriteBatch, id: string, data: Partial<T>): void;
+    createInBatch(batch: WriteBatch, data: Partial<Plaintext<T>> | FirestoreDocument): DocumentReference;
+    createWithIdInBatch(batch: WriteBatch, id: string, data: Partial<Plaintext<T>> | FirestoreDocument): void;
+    updateInBatch(batch: WriteBatch, id: string, data: Partial<Plaintext<T>>): void;
     deleteInBatch(batch: WriteBatch, id: string): void;
 }

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

@@ -268,6 +268,21 @@ export class BaseRepository {
         await batch.commit();
         return present.length;
     }
+    /*
+     * 🛑 Accepts the PLAINTEXT shape, because this method ENCRYPTS.
+     *
+     * `applyWriteHooks` runs `encryptPiiFields` over the subclass's `piiFields`,
+     * so a caller legitimately hands over a real email and Firestore holds
+     * ciphertext. Typing this `Partial<T>` demanded `Encrypted<string>` from
+     * every caller once the PII fields were branded — and the only way to make
+     * one without encrypting is `asEncrypted(value)`, which labels plaintext as
+     * ciphertext and is the misuse that helper's docstring forbids. The
+     * alternative was a cast at each of the dozens of write sites across
+     * fourteen repositories; one honest signature here is that change made once.
+     *
+     * `Plaintext<T>` is the identity on a document with no branded member, so
+     * this is a no-op for every repository holding no PII.
+     */
     async create(data) {
         try {
             const cleanData = prepareForFirestore({
@@ -315,6 +330,7 @@ export class BaseRepository {
      * NAME: `createWithId` reads as "create" and behaves as "replace", and that
      * gap is what made the wrong conclusion so easy to reach.
      */
+    // Plaintext<T> — these methods ENCRYPT via applyWriteHooks; see `create`.
     async createWithId(id, data) {
         try {
             const now = new Date();
@@ -339,6 +355,7 @@ export class BaseRepository {
             throw new DatabaseError(`Failed to create document with ID: ${id}: ${detailOf(error)}`, error);
         }
     }
+    /** Accepts the PLAINTEXT shape — see `create` for why. */
     async update(id, data) {
         try {
             const cleanData = prepareForFirestore({
@@ -496,6 +513,7 @@ export class BaseRepository {
         }));
         return docRef;
     }
+    // Plaintext<T> — these methods ENCRYPT via applyWriteHooks; see `create`.
     updateInTx(tx, id, data) {
         const docRef = this.getCollection().doc(id);
         tx.update(docRef, prepareForFirestore({ ...this.applyWriteHooks(data), updatedAt: new Date() }));
@@ -523,6 +541,7 @@ export class BaseRepository {
             updatedAt: now,
         }));
     }
+    // Plaintext<T> — these methods ENCRYPT via applyWriteHooks; see `create`.
     updateInBatch(batch, id, data) {
         const docRef = this.getCollection().doc(id);
         batch.update(docRef, prepareForFirestore({ ...this.applyWriteHooks(data), updatedAt: new Date() }));

package/dist/providers/db-firebase/rtdb-paths.d.ts

@@ -34,4 +34,16 @@ export declare const RTDB_PATHS: {
      * Pruned by `cleanupRtdbEvents`'s sixth block.
      */
     readonly CHAT_EVENTS: "chat_events";
+    /**
+     * Per-run progress for the sticker kiss-cut tracer — stage, pct, parts and
+     * shards done. The DURABLE record is `stickerTraceRuns.events[]`; this is
+     * only the live bar, which is why losing it is survivable and why the run
+     * document is what a failure is diagnosed from weeks later.
+     *
+     * 🛑 Pruned at SIXTY minutes, not fifteen. A `max`-tier fan-out across sixty
+     * parts can outlast a fifteen-minute window, and a channel pruned mid-run
+     * reads to the client as "it died" — the same false negative `EMAIL_EVENTS`
+     * carries a longer window to avoid.
+     */
+    readonly STICKER_TRACE: "sticker_trace";
 };

package/dist/providers/db-firebase/rtdb-paths.js

@@ -34,4 +34,16 @@ export const RTDB_PATHS = {
      * Pruned by `cleanupRtdbEvents`'s sixth block.
      */
     CHAT_EVENTS: "chat_events",
+    /**
+     * Per-run progress for the sticker kiss-cut tracer — stage, pct, parts and
+     * shards done. The DURABLE record is `stickerTraceRuns.events[]`; this is
+     * only the live bar, which is why losing it is survivable and why the run
+     * document is what a failure is diagnosed from weeks later.
+     *
+     * 🛑 Pruned at SIXTY minutes, not fifteen. A `max`-tier fan-out across sixty
+     * parts can outlast a fifteen-minute window, and a channel pruned mid-run
+     * reads to the client as "it died" — the same false negative `EMAIL_EVENTS`
+     * carries a longer window to avoid.
+     */
+    STICKER_TRACE: "sticker_trace",
 };

package/dist/react/ErrorBoundary.js

@@ -10,7 +10,12 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  */
 import { Component } from "react";
 import { Logger } from "../core/Logger.js";
-import { Button, Heading, Text } 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 { Button } from "../ui/components/Button.js";
+import { Heading, Text } from "../ui/components/Typography.js";
 import { trackError, ErrorCategory, ErrorSeverity, } from "../monitoring/error-tracking.js";
 function DefaultFallback({ error, onReset, }) {
     return (_jsxs("div", { role: "alert", style: {

package/dist/react/hooks/realtime-event-constants.d.ts

@@ -20,6 +20,7 @@ export declare const RealtimeEventType: {
     readonly CHAT: "chat";
     readonly BID: "bid";
     readonly BULK: "bulk";
+    readonly STICKER_TRACE: "sticker-trace";
 };
 export type RealtimeEventType = (typeof RealtimeEventType)[keyof typeof RealtimeEventType];
 export declare const RealtimeEventStatus: {

package/dist/react/hooks/realtime-event-constants.js

@@ -19,6 +19,14 @@ export const RealtimeEventType = {
     CHAT: "chat",
     BID: "bid",
     BULK: "bulk",
+    /*
+     * The sticker kiss-cut tracer's per-run progress channel. Added rather than
+     * reusing BULK: the type selects this event's message strings and its
+     * claim/path conventions, and a trace reports a STAGE out of eleven where a
+     * bulk job reports a count — borrowing BULK's vocabulary would make the
+     * progress row say the wrong thing about every failure.
+     */
+    STICKER_TRACE: "sticker-trace",
 };
 export const RealtimeEventStatus = {
     IDLE: "idle",

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;
@@ -2796,10 +2796,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 +2811,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 +3056,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 +3204,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 +4616,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>;
@@ -6354,8 +6347,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 +6365,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/encrypted.d.ts

@@ -0,0 +1,117 @@
+/**
+ * `Encrypted<T>` — the FORCING FUNCTION for ciphertext-by-default.
+ *
+ * ## The problem this exists to solve
+ *
+ * `audit-pii-coverage`'s R3 stages fourteen repositories whose `mapDoc`
+ * decrypts PII on EVERY read. The prescription — copy `SiteSettingsRepository`:
+ * leave `mapDoc` alone and expose plaintext through a NAMED getter with a
+ * masked variant — is right, and the migration had been staged for one reason:
+ *
+ *   **`tsc` cannot find the call sites.**
+ *
+ * Measured 2026-10-17: 147 distinct files touch a staged repository. And
+ * `PayoutDocument.sellerEmail` is declared `string` whether the value in it is
+ * ciphertext or plaintext, so a call site that gets the wrong one COMPILES. It
+ * then either renders `enc:v1:…` to an admin or publishes a decrypted email.
+ * There is no compile error, no runtime error, and nothing to grep for.
+ *
+ * Compare the `perPage` → `pageSize` rename done the same day: renaming one
+ * interface member turned all 65 consumers into compile errors and `tsc`
+ * handed over the list. That is the difference between a safe sweep and a
+ * 147-file guess, and it is purely a property of the TYPE.
+ *
+ * ## How it works
+ *
+ * A branded string. `Encrypted<string>` is assignable FROM nothing but itself,
+ * so every reader that wants a plain `string` must go through one of the two
+ * named accessors below — and until it does, it is a compile error naming the
+ * exact file and line.
+ *
+ * ```ts
+ * //   payout.sellerEmail            → Encrypted<string>   (what Firestore holds)
+ * //   plaintext(payout.sellerEmail) → string              (opt-in, named, auditable)
+ * //   maskedEmail(payout.sellerEmail) → string            (the UI default)
+ * ```
+ *
+ * The brand is erased at runtime: `Encrypted<string>` IS a string, so nothing
+ * changes about what is stored, sent or compared. It exists only to make the
+ * compiler ask the question at every site.
+ *
+ * ## 🛑 Branding a field is HALF a change, never a whole one
+ *
+ * The type must be made true in the same commit, by removing that
+ * repository's unconditional `mapDoc` decrypt. Branding a field whose value is
+ * still decrypted on read asserts something false, and the first `plaintext()`
+ * call would then double-decrypt — `decryptValue` passes a non-`enc:v1:`
+ * string through unchanged, so it would silently "work" and hide the lie.
+ *
+ * Convert ONE repository per change, smallest consumer count first. `tsc` then
+ * enumerates only that repository's readers, which is the whole point: a
+ * reviewable list per step instead of 147 at once.
+ */
+declare const ENCRYPTED_BRAND: unique symbol;
+/**
+ * A string that is CIPHERTEXT as it sits in Firestore.
+ *
+ * Erased at runtime — the VALUE is a string, so nothing changes about what is
+ * stored, sent or compared. The TYPE is not a string, and that is the point.
+ *
+ * ## 🛑 This was `T & { brand }`, and that version caught NO readers at all
+ *
+ * An intersection is a SUBTYPE of `string`, so `Encrypted<string>` was
+ * assignable to anything accepting a `string`. Measured directly: the write
+ * direction errored, while `maskName(cipher)`, `` `${cipher}` `` and
+ * `const s: string = cipher` all compiled in silence.
+ *
+ * So the fourteen-repository sweep enumerated every WRITE and not one READ —
+ * and this file's own docstring asserted the opposite, which is why the gap
+ * went unnoticed until `/reviews/[id]` was found rendering "Anonymous" for
+ * every reviewer (`findById` returned ciphertext, an `as Review` cast erased
+ * the brand, and `maskName` refuses ciphertext by design). Nine
+ * cross-repository writes were meanwhile double-encrypting PII, including the
+ * `upiId` two scheduled jobs send money to.
+ *
+ * A nominal shape is assignable to nothing that wants a `string`, so every
+ * reader becomes a compile error naming its file and line. That is the
+ * enumeration the intersection form could never produce.
+ *
+ * `__plain` is phantom — never read, never written, optional so no value has to
+ * carry it. It keeps `Encrypted<"a">` and `Encrypted<"b">` distinct rather than
+ * collapsing both to one opaque brand.
+ */
+export type Encrypted<T extends string = string> = {
+    readonly [ENCRYPTED_BRAND]: "pii";
+    readonly __plain?: T;
+};
+/**
+ * A document type with its `Encrypted<string>` members as plain `string`.
+ *
+ * ONE definition of "the plaintext shape", so each feature's `<Doc>Plain`
+ * alias and `BaseRepository`'s write signature agree by construction. Thirteen
+ * hand-rolled copies of this mapped type is thirteen chances to get the
+ * `undefined` handling subtly different, and the difference only shows up as a
+ * cast somebody adds to make one call site compile (Root Cause #75).
+ *
+ * `Extract<T[K], undefined>` preserves optionality: a field declared
+ * `Encrypted<string> | undefined` stays `string | undefined`, rather than
+ * becoming required.
+ */
+export type Plaintext<T> = {
+    [K in keyof T]: T[K] extends Encrypted<string> | null | undefined ? Extract<T[K], null | undefined> | string : Exclude<T[K], null | undefined> extends Date | ReadonlyArray<unknown> | ((...args: never[]) => unknown) ? T[K] : T[K] extends Date | ReadonlyArray<unknown> | ((...args: never[]) => unknown) ? T[K] : T[K] extends object | undefined ? Extract<T[K], undefined> | Plaintext<Exclude<T[K], undefined>> : T[K];
+};
+/**
+ * Mark a value as ciphertext. For a repository's own read path, where the value
+ * genuinely came out of Firestore encrypted.
+ *
+ * 🛑 Not for widening a plaintext value to satisfy a type. If a caller has
+ * plaintext and the field wants `Encrypted`, the value needs ENCRYPTING, not
+ * re-labelling — `encryptPii` is the function for that.
+ */
+export declare const asEncrypted: <T extends string>(value: T) => Encrypted<T>;
+/**
+ * Narrow a possibly-undefined ciphertext field. Saves every call site writing
+ * the same `value === undefined ? undefined : …` dance.
+ */
+export declare const asEncryptedMaybe: <T extends string>(value: T | undefined | null) => Encrypted<T> | undefined;
+export {};