@mohasinac/appkit 4.71.0 → 4.72.0

package/dist/features/audit-log/schemas/firestore.js

@@ -10,6 +10,14 @@
  * This is deliberately an MVP scope (instrumenting existing high-value call
  * sites), not an exhaustive every-write-path audit trail — see CLAUDE.md's
  * "Admin Audit Log" section for the full instrumented-action list.
+ *
+ * 🛑 NOT STRICTLY "ADMIN" ANY MORE. `allocation_random_assign` is written by
+ * the platform itself under a `"system:allocation"` sentinel, because the one
+ * property that action needs — an immutable, queryable record no seller can
+ * write or edit — is the property this collection already has and a log line
+ * does not. The collection name stays `adminAuditLog`; the question it answers
+ * widens from "what have admins done" to "what privileged or fairness-critical
+ * act happened, and on whose authority". See that value's own docstring.
  */
 export const ADMIN_AUDIT_LOG_COLLECTION = "adminAuditLog";
 export const AdminAuditActionValues = {
@@ -131,6 +139,49 @@ export const AdminAuditActionValues = {
      * question that follows a complaint is who wrote it.
      */
     SCAMMER_PROFILE_UPDATE: "scammer_profile_update",
+    /**
+     * A common-toggle card on the admin dashboard quick-jump (Phase 9, overhaul
+     * brief) flipped a site-settings boolean — maintenance mode, buyer-seller
+     * messaging, or the customer assistant. Each of the three has a wider
+     * blast radius than a single admin's own session (maintenance mode takes
+     * the whole site down for every visitor), so "who flipped this, and when"
+     * is the same question `store_status_change` already answers for stores.
+     */
+    COMMON_TOGGLE_CHANGE: "common_toggle_change",
+    /**
+     * The platform's RNG allocated a concealed item to one buyer's order line.
+     *
+     * 🛑 THE ONLY NON-ADMIN ACTION IN THIS TABLE, and the reason it belongs
+     * here anyway is the whole point of the surprise/reveal mechanic. The
+     * owner's framing: *"it is randomly generated so we have a trace — no
+     * seller can say you got a trash item when in reality you got the prize,
+     * because it was not transparent."*
+     *
+     * A trace is only a trace if it is immutable and inspectable. Until now the
+     * pick was recorded with `ctx.logger.info`, which is neither: logs rotate,
+     * are not queryable per order, and are not something a buyer or an auditor
+     * can be shown when a seller disputes what was sent. This collection is
+     * admin-SDK-write-only (`firestore.rules` is a blanket deny-all), carries no
+     * update path anywhere in the codebase, and is already rendered by
+     * `AdminAuditLogView` — so it is exactly the "immutable record someone can
+     * point at" the claim needs, and **a seller cannot write or edit a row in
+     * it.**
+     *
+     * `actorUid` is the `"system:allocation"` sentinel: the pick is a rule with
+     * an RNG attached, not a discretionary decision, and the same sentinel
+     * convention already exists for `"system:points-expiry"`. The absence of a
+     * human actor is itself the evidence — if an allocation row ever carried a
+     * real uid, that would be the fraud.
+     *
+     * Written INSIDE the assignment transaction, so the allocation and its trace
+     * commit or fail together. A best-effort `recordAdminAction` after the fact
+     * could leave an allocated order with no record of why it got what it got,
+     * which is the one state this must not be able to reach.
+     *
+     * `targetType: "orderItem"`, `targetId: "<orderId>"`, and the audit row's
+     * own id becomes the order line's `allocationId`.
+     */
+    ALLOCATION_RANDOM_ASSIGN: "allocation_random_assign",
 };
 export const ADMIN_AUDIT_LOG_FIELDS = {
     ACTOR_UID: "actorUid",

package/dist/features/auth/actions/profile-actions.d.ts

@@ -28,11 +28,11 @@ export declare function getUserSessions(userId: string): Promise<import("..").Se
  * it rather than read off `users/{uid}.stats`.
  *
  * 🛑 `users/{uid}.stats.*` HAS NO WRITER. Measured 2026-10-23: every occurrence
- * of `stats.totalOrders` / `auctionsWon` / `itemsSold` / `reviewsCount` across
+ * of `stats.totalOrders` / `collectorDropsWon` / `itemsSold` / `reviewsCount` across
  * both repos is a READ, and the only `stats.itemsSold` write in the codebase is
  * `StoreRepository`'s, on the STORE document. So the stored numbers are
  * whatever `users-seed-data.ts` hardcoded — the admin persona ships
- * `{ totalOrders: 20, auctionsWon: 2, itemsSold: 200 }` — and a real signup gets
+ * `{ totalOrders: 20, collectorDropsWon: 2, itemsSold: 200 }` — and a real signup gets
  * `DEFAULT_USER_DATA.stats`, all zeros, which stay zero after twenty orders.
  *
  * A number nobody maintains is worse than no number: it is indistinguishable
@@ -55,8 +55,8 @@ export declare function getUserSessions(userId: string): Promise<import("..").Se
 export interface BuyerActivityStats {
     /** Orders this account placed, all lanes. */
     totalOrders?: number;
-    /** Orders that came from winning (or buying out) an auction. */
-    auctionsWon?: number;
+    /** Orders that came from winning (or buying out) a collector drop. */
+    collectorDropsWon?: number;
     /** Reviews this account WROTE — the set `/user/reviews` lists. */
     reviewsCount?: number;
 }
@@ -78,7 +78,7 @@ export declare const getBuyerActivityStats: (uid: string) => Promise<BuyerActivi
  * It deliberately does NOT reach the sidebar's own profile block, which is the
  * buyer's view of their own account: see `AppLayoutShell`.
  */
-export declare function getProfileStats(user: Pick<UserDocument, "uid" | "id" | "storeId">): Promise<BuyerActivityStats & {
+export declare function getProfileStats(user: Pick<UserDocument, "uid" | "id">): Promise<BuyerActivityStats & {
     itemsSold?: number;
 }>;
 /**
@@ -116,7 +116,9 @@ export declare function resolveProfileUser(identifier: string): Promise<UserDocu
  * would have left a signed-in user reading real counts in the nav and seeded
  * ones on their own public profile, which is a worse state than both being wrong.
  */
-export declare const getPublicUserProfile: (userId: string) => Promise<(Pick<UserDocument, "id" | "slug" | "displayName" | "photoURL" | "role" | "createdAt" | "storeId" | "storeSlug" | "publicProfile"> & {
+export declare const getPublicUserProfile: (userId: string) => Promise<(Pick<UserDocument, "id" | "slug" | "displayName" | "photoURL" | "role" | "createdAt" | "publicProfile"> & {
+    storeId?: string;
+    storeSlug?: string;
     stats: BuyerActivityStats & {
         itemsSold?: number;
     };

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

@@ -14,6 +14,7 @@ import { ProductStatusValues } from "../../products/schemas/index.js";
 import { reviewRepository } from "../../reviews/repository/reviews.repository.js";
 import { orderRepository } from "../../orders/repository/orders.repository.js";
 import { storeRepository } from "../../stores/repository/store.repository.js";
+import { sellerProfileRepository } from "../../seller/repository/seller-profile.repository.js";
 export async function updateUserProfile(userId, input) {
     const finalPhotoURL = await finalizeStagedMediaField(input.photoURL);
     const data = finalPhotoURL !== undefined ? { ...input, photoURL: finalPhotoURL } : input;
@@ -32,15 +33,15 @@ export async function getUserSessions(userId) {
  */
 export const getBuyerActivityStats = cache(async function getBuyerActivityStats(uid) {
     const route = "profile:buyer-activity-stats";
-    const [totalOrders, auctionsWon, reviewsCount] = await Promise.all([
+    const [totalOrders, collectorDropsWon, reviewsCount] = await Promise.all([
         safeRead(() => orderRepository.countForUser(uid), {
             route,
             key: "orders:total",
             fallback: undefined,
         }),
-        safeRead(() => orderRepository.countForUser(uid, "auction"), {
+        safeRead(() => orderRepository.countForUser(uid, "collector-drop"), {
             route,
-            key: "orders:auction",
+            key: "orders:collector-drop",
             fallback: undefined,
         }),
         safeRead(() => reviewRepository.countByUser(uid), {
@@ -49,7 +50,7 @@ export const getBuyerActivityStats = cache(async function getBuyerActivityStats(
             fallback: undefined,
         }),
     ]);
-    return { totalOrders, auctionsWon, reviewsCount };
+    return { totalOrders, collectorDropsWon, reviewsCount };
 });
 /**
  * Buyer activity plus, for an account that owns a store, the one SELLER number
@@ -65,10 +66,16 @@ export const getBuyerActivityStats = cache(async function getBuyerActivityStats(
  */
 export async function getProfileStats(user) {
     const uid = user.uid ?? user.id;
+    // storeId is seller-only data — sellerProfiles, not users.
+    const sellerProfile = await safeRead(() => sellerProfileRepository.findById(uid), {
+        route: "profile:store-items-sold",
+        key: "sellerProfile:findById",
+        fallback: null,
+    });
     const [activity, itemsSold] = await Promise.all([
         getBuyerActivityStats(uid),
-        user.storeId
-            ? safeRead(async () => (await storeRepository.findById(user.storeId))?.stats
+        sellerProfile?.storeId
+            ? safeRead(async () => (await storeRepository.findById(sellerProfile.storeId))?.stats
                 ?.itemsSold, {
                 route: "profile:store-items-sold",
                 key: "store:itemsSold",
@@ -125,6 +132,8 @@ export const getPublicUserProfile = cache(async function getPublicUserProfile(us
     const user = await resolveProfileUser(userId);
     if (!user)
         return null;
+    // storeId/storeSlug are seller-only data — sellerProfiles, not users.
+    const sellerProfile = await sellerProfileRepository.findById(user.id);
     return {
         id: user.id,
         slug: user.slug,
@@ -132,8 +141,8 @@ export const getPublicUserProfile = cache(async function getPublicUserProfile(us
         photoURL: user.photoURL,
         role: user.role,
         createdAt: user.createdAt,
-        storeId: user.storeId,
-        storeSlug: user.storeSlug,
+        storeId: sellerProfile?.storeId,
+        storeSlug: sellerProfile?.storeSlug,
         publicProfile: user.publicProfile,
         stats: await getProfileStats(user),
     };

package/dist/features/auth/auth-helpers.d.ts

@@ -1,11 +1,195 @@
 import type { UserRole } from "./types";
+import { rolesOf, holdsRole, holdsAnyRole } from "./role-predicates";
+import type { RoleCarrier } from "./role-predicates";
+import type { Permission } from "./permissions/constants";
 export interface DefaultRoleOptions {
     adminEmails?: string[];
     adminRole?: UserRole;
     fallbackRole?: UserRole;
 }
-export declare function hasRole(userRole: UserRole, requiredRole: UserRole): boolean;
-export declare function hasAnyRole(userRole: UserRole, requiredRoles: UserRole[]): boolean;
+/** Highest hierarchy rank among the roles this carrier holds. */
+export declare function maxRoleLevel(user: RoleCarrier): number;
+/**
+ * Is this user AT LEAST `requiredRole` in the hierarchy, considering every
+ * role they hold?
+ *
+ * ⚠ Hierarchy-aware on purpose — `hasRole(u, "seller")` is true for an admin,
+ * which is what "admin sees everything, everywhere" means at this layer. For
+ * exact set membership (e.g. "does this account literally hold `seller`") use
+ * `holdsRole` from ./role-predicates.
+ *
+ * Accepts a user-shaped carrier OR a bare role string, so the ~5 existing
+ * `hasRole(user.role, "seller")` call sites keep compiling while new ones pass
+ * the whole user and get the union.
+ */
+export declare function hasRole(user: RoleCarrier | UserRole, requiredRole: UserRole): boolean;
+/** `hasRole` against any of `requiredRoles`. */
+export declare function hasAnyRole(user: RoleCarrier | UserRole, requiredRoles: readonly UserRole[]): boolean;
+/**
+ * Re-exported so a caller that needs EXACT membership (no hierarchy) does not
+ * have to know that it lives in a different module — one import, one helper.
+ */
+export { rolesOf, holdsRole, holdsAnyRole };
+/**
+ * The resolved permission answer for a user: either "is admin, bypasses
+ * everything" or an explicit permission list.
+ *
+ * 🛑 One shape, shared by the pure client-safe resolver below and the
+ * Firestore-reading `getServerPermissions`, so a surface cannot be gated one
+ * way on the server and another in the UI.
+ */
+export interface ResolvedPermissions {
+    /** true when the user holds `admin` — bypasses all permission checks. */
+    isAdmin: boolean;
+    /** Union of every permission granted by the held roles plus explicit grants. */
+    permissions: Permission[];
+}
+/** Anything carrying roles plus the per-user explicit permission grants. */
+export type PermissionCarrier = {
+    role?: string | null;
+    roles?: readonly string[] | null;
+    permissions?: readonly string[] | null;
+} | null | undefined;
+/**
+ * ── `permissionsFor(user)` — the UNION across every held role ────────────────
+ *
+ * Pure and synchronous: it resolves from the object it is handed and reads no
+ * database. `getServerPermissions(uid)` is the async wrapper that fetches the
+ * document first and then calls this, so there is one resolution rule rather
+ * than a server copy and a client copy that drift.
+ *
+ * Three sources are merged:
+ *   1. `ROLE_PERMISSION_BUNDLES[role]` for every role held — the DATA layer
+ *      that makes "give the auditor role the ledger" a config edit.
+ *   2. The user's own `permissions[]` array — per-person grants on top of the
+ *      bundle, which is how an employee is actually configured today.
+ *   3. `admin` short-circuits to `isAdmin: true`, which every check treats as
+ *      "yes" without consulting the array at all.
+ */
+export declare function permissionsFor(user: PermissionCarrier): ResolvedPermissions;
+/**
+ * Does this user have `required`? Admin always does.
+ *
+ * This is the function a mechanism should call. `hasRole` exists for the gates
+ * that are genuinely about rank (portal routing, the hierarchy-ordered
+ * `requireRole`); anything that is about a CAPABILITY belongs here.
+ */
+export declare function can(user: PermissionCarrier, required: Permission): boolean;
+/** `can` against any of `required` — the OR of several permissions. */
+export declare function canAny(user: PermissionCarrier, required: readonly Permission[]): boolean;
+/**
+ * Every moderation site, keyed by what the actor is trying to DO.
+ *
+ * Keys are action names rather than route paths on purpose: the same power is
+ * reached from an API route, a server action and a form shell, and all three
+ * must resolve to the same permission or the gate is half-converted.
+ */
+export declare const MODERATION_PERMISSIONS: {
+    /** Edit any review regardless of authorship, including its moderation status. */
+    readonly "reviews:moderate": "admin:reviews:write";
+    /** Delete any review regardless of authorship. */
+    readonly "reviews:remove": "admin:reviews:delete";
+    /** Edit any listing regardless of store ownership. */
+    readonly "products:moderate": "admin:products:write";
+    /** Archive any listing regardless of store ownership. */
+    readonly "products:remove": "admin:products:delete";
+    /** Read a support ticket you did not open. */
+    readonly "support-tickets:view": "admin:support-tickets:read";
+    /** Reply to a support ticket as staff (and email the owner). */
+    readonly "support-tickets:reply": "admin:support-tickets:write";
+    /**
+     * See EVERY entrant on a product or event draw, not just your own entries.
+     * `admin:moderation:read` rather than a bids/offers key: the draw-entry
+     * queues are reached from the moderation hub, which this same key gates.
+     */
+    readonly "draw-entries:view": "admin:moderation:read";
+    /**
+     * Flag a suspicious draw entry with a moderator note — a WRITE on the
+     * moderation queue, so `admin:moderation:write` and not the `:read` key that
+     * gates merely looking at it.
+     */
+    readonly "draw-entries:flag": "admin:moderation:write";
+    /**
+     * Verify a manual payment, extend a payment window, or reject a proof as
+     * fraud. 🛑 The money path — its own key, in one narrow preset only.
+     */
+    readonly "orders:payment-override": "admin:orders:payment-override";
+    /** Act on an order you neither bought nor sold — e.g. raise a dispute on it. */
+    readonly "orders:act-on-any": "admin:orders:write";
+};
+/** The action names above, as a type. */
+export type ModerationAction = keyof typeof MODERATION_PERMISSIONS;
+/** Every moderation action, as a runtime value — for exhaustive assertions. */
+export declare const ALL_MODERATION_ACTIONS: ModerationAction[];
+/**
+ * May this user perform moderation `action`?
+ *
+ * ⚠ SYNCHRONOUS, so it resolves ONLY from the object handed to it. That is
+ * correct for a `UserDocument` or anything else carrying `permissions[]`, and
+ * WRONG for an API-route `user`: `createRouteHandler`'s session payload carries
+ * `uid`/`role`/`roles` and no `permissions` array, so a per-person grant is
+ * invisible to it and every employee would be denied. Server routes and
+ * actions must use `canModerateServer(uid, action)` instead, which reads the
+ * document first. The two share this one resolution rule.
+ */
+export declare function canModerate(user: PermissionCarrier, action: ModerationAction): boolean;
+/**
+ * ── 🛑 DISPLAY ONLY ──────────────────────────────────────────────────────────
+ *
+ * The role to SHOW for this user — a badge, a profile line, a default tab.
+ *
+ * **It must never make an authorization decision.** A `primaryRole` that gates
+ * anything is the single-role bug returning under a new name: an admin whose
+ * primary role reads "user" would be locked out of `/admin` while genuinely
+ * holding `admin`. That is precisely the failure mode 1.43 exists to remove,
+ * so every gate reads `rolesOf` / `permissionsFor` instead.
+ *
+ * Resolution: the stored `primaryRole` when the user actually still holds it
+ * (a role can be removed after being chosen as primary), otherwise the
+ * highest-ranked role held. Never returns a role the user does not hold.
+ */
+export declare function primaryRoleOf(user: (RoleCarrier & {
+    primaryRole?: string | null;
+}) | null | undefined): UserRole;
+/**
+ * ── The normalisation every read path applies ────────────────────────────────
+ *
+ * Mutates and returns `doc` with all three role fields made consistent:
+ * `roles` (authority), `primaryRole` (display, always actually held) and
+ * `role` (legacy scalar, set to the HIGHEST-RANKED held role).
+ *
+ * 🛑 ONE function, called from `UserRepository.mapDoc` so every read path
+ * normalises, and from `scripts/backfill-user-roles.mjs` so the stored data
+ * ends up matching exactly what readers already see. A second copy of this
+ * rule is how a backfill and a dual-read disagree.
+ *
+ * `role` is the highest rank rather than `primaryRole` on purpose — see the
+ * `mapDoc` comment: a not-yet-converted guard comparing the scalar must not
+ * under-grant.
+ */
+export declare function normalizeUserRoleFields<T extends {
+    role?: string | null;
+    roles?: readonly string[] | null;
+    primaryRole?: string | null;
+}>(doc: T): T;
+/** Install the configured cap. Call once at boot from the settings loader. */
+export declare function setMaxRolesPerUser(value: number | null | undefined): void;
+/** The effective cap: the configured value, else the default. */
+export declare function getMaxRolesPerUser(): number;
+/**
+ * Validate a proposed role set.
+ *
+ * **No forbidden combinations** (owner decision) — the only rules are
+ * non-empty, known roles, and the cap. Returns the normalised set so a caller
+ * cannot accidentally persist duplicates or a legacy alias.
+ */
+export declare function validateRoleSet(proposed: readonly string[]): {
+    ok: true;
+    roles: UserRole[];
+} | {
+    ok: false;
+    error: string;
+};
 export declare function getDefaultRole(email?: string, options?: DefaultRoleOptions): UserRole;
 export declare function formatAuthProvider(provider: string): string;
 export declare function isSessionExpired(expiresAt: Date | string): boolean;