@mohasinac/appkit 4.52.4 → 4.53.0

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 {};

package/dist/security/encrypted.js

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

package/dist/security/index.d.ts

@@ -4,7 +4,10 @@ export type { RateLimitConfig, RateLimitResult } from "./rate-limit";
 export { requireAuth, requireRole, requireOwnership, requireEmailVerified, requireActiveAccount, canChangeRole, getRoleLevel, } from "./authorization";
 export type { UserRole } from "./authorization";
 export { redactPii, safeDisplayName, safeDisplayEmail, maskIp } from "./pii-redact";
-export { encryptValue, decryptValue, hmacBlindIndex, encryptPiiFields, decryptPiiFields, encryptPii, decryptPii, piiBlindIndex, piiIndicesFor, getPiiConfigError, encryptPayoutDetails, decryptPayoutDetails, encryptShippingConfig, decryptShippingConfig, encryptPayoutBankAccount, decryptPayoutBankAccount, } from "./pii-encrypt";
-export { isPiiEncrypted, maskName, maskEmail, maskPublicReview, maskPublicBid, maskPublicEventEntry, maskOfferForSeller, ENC_PREFIX, HMAC_PREFIX, } from "./pii-mask";
+export { asEncrypted, asEncryptedMaybe } from "./encrypted";
+export type { Encrypted } from "./encrypted";
+export { encryptValue, decryptValue, hmacBlindIndex, encryptPiiFields, decryptPiiFields, encryptPii, decryptPii, piiBlindIndex, piiIndicesFor, getPiiConfigError, encryptPayoutDetails, decryptPayoutDetails, encryptShippingConfig, decryptShippingConfig, } from "./pii-encrypt";
+export { revealPii, maskPii, revealPiiAll, maskPiiAll } from "./pii-accessors";
+export { isPiiEncrypted, maskName, maskEmail, maskPhone, maskPublicReview, maskPublicBid, maskPublicEventEntry, maskOfferForSeller, ENC_PREFIX, HMAC_PREFIX, } from "./pii-mask";
 export { USER_PII_FIELDS, USER_PII_INDEX_MAP, ADDRESS_PII_FIELDS, ORDER_PII_FIELDS, PAYOUT_PII_FIELDS, PAYOUT_PII_INDEX_MAP, BID_PII_FIELDS, TOKEN_PII_FIELDS, TOKEN_PII_INDEX_MAP, REVIEW_PII_FIELDS, REVIEW_PII_INDEX_MAP, OFFER_PII_FIELDS, EVENT_ENTRY_PII_FIELDS, LOTTERY_ENTRY_PII_FIELDS, PAYMENT_METHOD_PII_FIELDS, CONVERSATION_PII_FIELDS, MESSAGE_PII_FIELDS, } from "./pii-schemas";
 export { encryptSecret, decryptSecret, isSecretEncrypted, maskSecret, } from "./settings-encryption";

package/dist/security/index.js

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

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

@@ -0,0 +1,71 @@
+/**
+ * The two NAMED accessors that replace an unconditional `mapDoc` decrypt.
+ *
+ * ## Why this module exists
+ *
+ * `audit-pii-coverage`'s R3 stages fourteen repositories whose `mapDoc`
+ * decrypted PII on every read, so ciphertext never left the database and every
+ * caller silently handled plaintext. The prescription — copy
+ * `SiteSettingsRepository`: leave `mapDoc` alone and expose plaintext through a
+ * NAMED getter with a masked variant — is per-repository, and writing it
+ * fourteen times would be fourteen chances for the field→mask mapping to
+ * drift (Root Cause #75). So the rule lives here once and each repository
+ * delegates.
+ *
+ * ```ts
+ *   repo.findById(id)                  → PII fields are Encrypted<string>
+ *   repo.revealFor(doc)                → plaintext, opt-in and named
+ *   repo.maskedFor(doc)                → masked, the UI default
+ * ```
+ *
+ * ## 🛑 Masking must DECRYPT FIRST
+ *
+ * This is the trap worth stating, because getting it wrong is silent and looks
+ * like success. `maskName`/`maskEmail` in `pii-mask.ts` both begin with
+ * `if (hasEncPrefix(value)) return "Anonymous" / "***@***.***"` — a deliberate
+ * guard so ciphertext can never reach a UI. Once `mapDoc` stops decrypting,
+ * handing a stored field straight to `maskName` therefore returns "Anonymous"
+ * for EVERY row: no error, no ciphertext leak, and a masked column that is
+ * uniformly useless instead of showing "R*** K***". `maskPii` decrypts and
+ * then masks.
+ *
+ * ## Field → mask is by NAME CLASS, deliberately
+ *
+ * An email masks differently from a phone from a person's name, and the field
+ * lists these repositories already declare (`*_PII_FIELDS`) carry no type
+ * information. Classifying on the field name is the only signal available, and
+ * it is the same approach `pii-redact.ts` has always used for logs — the
+ * difference being that this module uses the USER-FACING masks from
+ * `pii-mask.ts` rather than the log-oriented ones.
+ *
+ * 🛑 The fallback is `maskName`, not "return as-is". An unrecognised PII field
+ * name must degrade toward LESS disclosure; returning the plaintext would make
+ * a new field silently public the moment someone adds it to a `*_PII_FIELDS`
+ * list without touching this file.
+ *
+ * @tag domain:security
+ * @tag layer:security
+ * @tag access:server-only
+ * @tag sideEffects:none
+ */
+/**
+ * Decrypt the named PII fields. **Opt-in and named**: every call site is a
+ * deliberate decision that shows up in review and in a grep.
+ *
+ * The return type is the caller's plaintext-facing shape. That cast is the one
+ * place it is legitimate: this function performs the decryption that makes the
+ * `Encrypted<…>` brand false, which is exactly what the brand is for.
+ */
+export declare function revealPii<Plain extends object>(doc: object, piiFields: readonly string[]): Plain;
+/**
+ * Decrypt, then mask. **The default a UI should reach for.**
+ *
+ * Returns the same shape as `revealPii` because a masked value is still a
+ * displayable string — the difference is in what it contains, which is why the
+ * two accessors must be separately named rather than one taking a boolean.
+ */
+export declare function maskPii<Plain extends object>(doc: object, piiFields: readonly string[]): Plain;
+/** Array form of `revealPii`, for list reads. */
+export declare function revealPiiAll<Plain extends object>(docs: readonly object[], piiFields: readonly string[]): Plain[];
+/** Array form of `maskPii`, for list reads. */
+export declare function maskPiiAll<Plain extends object>(docs: readonly object[], piiFields: readonly string[]): Plain[];