@mohasinac/appkit 2.1.3 → 2.3.0

package/src/security/pii-encrypt.ts

@@ -1,117 +0,0 @@
-/**
- * PII Encryption Utilities — AES-256-GCM with HMAC-SHA256 blind indexes.
- *
- * Environment variables required (server-side only):
- *   PII_ENCRYPTION_KEY — 32-byte hex string (64 chars) for AES-256-GCM
- *   PII_HMAC_KEY       — 32-byte hex string (64 chars) for HMAC-SHA256
- *                        (defaults to PII_ENCRYPTION_KEY if absent)
- *
- * Ciphertext format: "enc:v1:<iv_b64>:<ciphertext_b64>:<authtag_b64>"
- * Blind index format: "hmac-sha256:<sha256_hex>"
- */
-import {
-  createCipheriv,
-  createDecipheriv,
-  randomBytes,
-  createHmac,
-} from "crypto";
-
-const ALGO = "aes-256-gcm";
-export const ENC_PREFIX = "enc:v1:";
-export const HMAC_PREFIX = "hmac-sha256:";
-
-function getEncKey(): Buffer {
-  const raw = process.env["PII_ENCRYPTION_KEY"] ?? "";
-  if (!raw)
-    throw new Error(
-      "PII_ENCRYPTION_KEY env var is not set — cannot encrypt PII fields",
-    );
-  return Buffer.from(raw, "hex");
-}
-
-function getHmacKey(): Buffer {
-  const raw =
-    process.env["PII_HMAC_KEY"] ?? process.env["PII_ENCRYPTION_KEY"] ?? "";
-  if (!raw)
-    throw new Error(
-      "PII_HMAC_KEY env var is not set — cannot generate blind PII index",
-    );
-  return Buffer.from(raw, "hex");
-}
-
-/** Encrypt a plaintext string with AES-256-GCM. */
-export function encryptValue(plaintext: string): string {
-  const key = getEncKey();
-  const iv = randomBytes(12);
-  const cipher = createCipheriv(ALGO, key, iv);
-  const enc = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
-  const tag = cipher.getAuthTag();
-  return `${ENC_PREFIX}${iv.toString("base64")}:${enc.toString("base64")}:${tag.toString("base64")}`;
-}
-
-/** Decrypt an AES-256-GCM ciphertext produced by `encryptValue`. */
-export function decryptValue(ciphertext: string): string {
-  if (!ciphertext.startsWith(ENC_PREFIX)) return ciphertext;
-  const inner = ciphertext.slice(ENC_PREFIX.length);
-  const parts = inner.split(":");
-  if (parts.length !== 3)
-    throw new Error(`Invalid PII ciphertext: ${ciphertext}`);
-  const [ivB64, encB64, tagB64] = parts as [string, string, string];
-  const key = getEncKey();
-  const iv = Buffer.from(ivB64, "base64");
-  const encrypted = Buffer.from(encB64, "base64");
-  const tag = Buffer.from(tagB64, "base64");
-  const decipher = createDecipheriv(ALGO, key, iv);
-  decipher.setAuthTag(tag);
-  return Buffer.concat([decipher.update(encrypted), decipher.final()]).toString(
-    "utf8",
-  );
-}
-
-/**
- * Produce a deterministic HMAC-SHA256 blind index for a PII value.
- * Used for equality lookups without decrypting (e.g. find-by-email).
- */
-export function hmacBlindIndex(value: string): string {
-  const key = getHmacKey();
-  const hash = createHmac("sha256", key).update(value).digest("hex");
-  return `${HMAC_PREFIX}${hash}`;
-}
-
-/**
- * Encrypt specified PII fields in a Firestore document.
- * For each encrypted field, a `<field>Index` blind-index sibling is added.
- * Already-encrypted values (prefix `enc:v1:`) are left unchanged.
- */
-export function encryptPiiFields<T extends Record<string, unknown>>(
-  doc: T,
-  piiFields: string[],
-): T {
-  const result = { ...doc } as Record<string, unknown>;
-  for (const field of piiFields) {
-    const value = doc[field];
-    if (typeof value !== "string" || !value) continue;
-    if (value.startsWith(ENC_PREFIX)) continue; // already encrypted
-    result[field] = encryptValue(value);
-    result[`${field}Index`] = hmacBlindIndex(value);
-  }
-  return result as T;
-}
-
-/**
- * Decrypt specified PII fields in a Firestore document.
- * Fields that are not encrypted (no `enc:v1:` prefix) are passed through.
- */
-export function decryptPiiFields<T extends Record<string, unknown>>(
-  doc: T,
-  piiFields: string[],
-): T {
-  const result = { ...doc } as Record<string, unknown>;
-  for (const field of piiFields) {
-    const value = doc[field];
-    if (typeof value === "string" && value.startsWith(ENC_PREFIX)) {
-      result[field] = decryptValue(value);
-    }
-  }
-  return result as T;
-}

package/src/security/pii-redact.ts

@@ -1,133 +0,0 @@
-/**
- * PII Redaction Utility
- *
- * Recursively sanitizes objects before logging by masking or redacting
- * known PII (Personally Identifiable Information) field names.
- *
- * - Secrets (password, token, apiKey, etc.) → "[REDACTED]"
- * - Emails → partial mask: "mo***@gmail.com"
- * - Phones → last 4 digits: "***9876"
- * - Names → first char + asterisks: "J********"
- * - Addresses, financial IDs → "[REDACTED]"
- * - IPs → first octet only: "192.***.***.***"
- */
-
-const MAX_DEPTH = 10;
-
-/** Keys whose values are fully replaced with "[REDACTED]" */
-const REDACT_KEYS = new Set([
-  "password",
-  "secret",
-  "apiKey",
-  "apiSecret",
-  "token",
-  "refreshToken",
-  "accessToken",
-  "authorization",
-  "cookie",
-  "sessionToken",
-  "accountNumber",
-  "ifscCode",
-  "upiId",
-  "bankAccount",
-  "pan",
-  "panNumber",
-  "aadhar",
-  "aadhaar",
-  "ssn",
-  "gstin",
-  "gstNumber",
-  "addressLine1",
-  "addressLine2",
-  "address",
-  "shippingAddress",
-  "postalCode",
-  "pincode",
-  "zipCode",
-]);
-
-/** Keys whose string values get email masking */
-const EMAIL_KEYS = new Set([
-  "email",
-  "userEmail",
-  "sellerEmail",
-  "shiprocketEmail",
-]);
-
-/** Keys whose string values get phone masking */
-const PHONE_KEYS = new Set(["phone", "phoneNumber", "mobileNumber"]);
-
-/** Keys whose string values get name masking */
-const NAME_KEYS = new Set([
-  "displayName",
-  "fullName",
-  "firstName",
-  "lastName",
-  "userName",
-]);
-
-/** Keys whose string values get IP masking */
-const IP_KEYS = new Set(["ip", "ipAddress"]);
-
-function maskEmail(value: string): string {
-  const atIndex = value.indexOf("@");
-  if (atIndex <= 0) return "[REDACTED]";
-  const local = value.slice(0, atIndex);
-  const domain = value.slice(atIndex);
-  if (local.length <= 2) return `${local[0]}***${domain}`;
-  return `${local.slice(0, 2)}***${domain}`;
-}
-
-function maskPhone(value: string): string {
-  const digits = value.replace(/\D/g, "");
-  if (digits.length < 4) return "[REDACTED]";
-  return `***${digits.slice(-4)}`;
-}
-
-function maskName(value: string): string {
-  if (!value || value.length < 2) return "[REDACTED]";
-  return `${value[0]}${"*".repeat(Math.min(value.length - 1, 8))}`;
-}
-
-function maskIp(value: string): string {
-  const parts = value.split(".");
-  if (parts.length === 4) return `${parts[0]}.***.***.***`;
-  return "[REDACTED]";
-}
-
-function redactStringValue(key: string, value: string): string {
-  if (REDACT_KEYS.has(key)) return "[REDACTED]";
-  if (EMAIL_KEYS.has(key)) return maskEmail(value);
-  if (PHONE_KEYS.has(key)) return maskPhone(value);
-  if (NAME_KEYS.has(key)) return maskName(value);
-  if (IP_KEYS.has(key)) return maskIp(value);
-  return value;
-}
-
-/**
- * Recursively redact PII from a data object before logging.
- *
- * Returns a new object with sensitive fields masked — the original is
- * never mutated.
- */
-export function redactPii(data: unknown, depth = 0): unknown {
-  if (depth > MAX_DEPTH) return "[MAX_DEPTH]";
-  if (data === null || data === undefined) return data;
-  if (typeof data !== "object") return data;
-
-  if (Array.isArray(data)) {
-    return data.map((item) => redactPii(item, depth + 1));
-  }
-
-  const result: Record<string, unknown> = {};
-  for (const [key, value] of Object.entries(data as Record<string, unknown>)) {
-    if (typeof value === "string") {
-      result[key] = redactStringValue(key, value);
-    } else if (typeof value === "object" && value !== null) {
-      result[key] = redactPii(value, depth + 1);
-    } else {
-      result[key] = value;
-    }
-  }
-  return result;
-}

package/src/security/rate-limit.ts

@@ -1,170 +0,0 @@
-/**
- * Rate Limiting
- *
- * Sliding-window rate limiter. Designed for free tier:
- * - Defaults to in-memory rate limiting (no external service required)
- * - Upstash Redis optional for distributed deployments (removed from free tier)
- *
- * On Vercel Free + Firebase Blaze free tier: uses in-memory only
- *
- * Legacy Upstash support (if UPSTASH_REDIS_REST_URL/TOKEN set):
- *   UPSTASH_REDIS_REST_URL
- *   UPSTASH_REDIS_REST_TOKEN
- */
-
-import type { NextRequest } from "next/server.js";
-
-export interface RateLimitConfig {
-  /** Maximum requests allowed in the window */
-  limit: number;
-  /** Time window in seconds */
-  window: number;
-  /** Custom identifier (default: IP address) */
-  identifier?: string;
-}
-
-export interface RateLimitResult {
-  success: boolean;
-  limit: number;
-  remaining: number;
-  reset: number;
-  error?: string;
-}
-
-// ─── IP extraction ────────────────────────────────────────────────────────────
-
-function getClientIP(request: NextRequest | Request): string {
-  const forwarded = request.headers.get("x-forwarded-for");
-  if (forwarded) return forwarded.split(",")[0].trim();
-  const realIP = request.headers.get("x-real-ip");
-  if (realIP) return realIP;
-  return "unknown";
-}
-
-// ─── Upstash-backed limiter ───────────────────────────────────────────────────
-
-let upstashLimiter:
-  | ((ip: string, limit: number, window: number) => Promise<RateLimitResult>)
-  | null = null;
-
-async function getUpstashLimiter() {
-  if (upstashLimiter) return upstashLimiter;
-
-  const url = process.env.UPSTASH_REDIS_REST_URL;
-  const token = process.env.UPSTASH_REDIS_REST_TOKEN;
-  if (!url || !token) return null;
-
-  const { Redis } = await import("@upstash/redis");
-  const { Ratelimit } = await import("@upstash/ratelimit");
-
-  const redis = new Redis({ url, token });
-  const cache = new Map<string, import("@upstash/ratelimit").Ratelimit>();
-
-  upstashLimiter = async (
-    ip: string,
-    limit: number,
-    window: number,
-  ): Promise<RateLimitResult> => {
-    const key = `${limit}:${window}`;
-    if (!cache.has(key)) {
-      cache.set(
-        key,
-        new Ratelimit({
-          redis,
-          limiter: Ratelimit.slidingWindow(limit, `${window} s`),
-          prefix: "mohasinac:rl",
-        }),
-      );
-    }
-    const result = await cache.get(key)!.limit(ip);
-    const reset = Math.ceil(result.reset / 1000);
-    return {
-      success: result.success,
-      limit: result.limit,
-      remaining: result.remaining,
-      reset,
-      error: result.success
-        ? undefined
-        : `Rate limit exceeded. Try again at ${new Date(reset * 1000).toISOString()}`,
-    };
-  };
-
-  return upstashLimiter;
-}
-
-// ─── In-memory fallback ───────────────────────────────────────────────────────
-
-const memStore = new Map<string, { count: number; resetAt: number }>();
-
-function inMemoryLimit(
-  identifier: string,
-  limit: number,
-  window: number,
-): RateLimitResult {
-  const now = Date.now();
-  const windowMs = window * 1000;
-  let entry = memStore.get(identifier);
-  if (!entry || now > entry.resetAt) {
-    entry = { count: 0, resetAt: now + windowMs };
-    memStore.set(identifier, entry);
-  }
-  entry.count++;
-  const remaining = Math.max(0, limit - entry.count);
-  const reset = Math.ceil(entry.resetAt / 1000);
-  if (entry.count > limit) {
-    return {
-      success: false,
-      limit,
-      remaining: 0,
-      reset,
-      error: `Rate limit exceeded. Try again in ${Math.ceil((entry.resetAt - now) / 1000)} seconds`,
-    };
-  }
-  return { success: true, limit, remaining, reset };
-}
-
-// ─── Public API ───────────────────────────────────────────────────────────────
-
-/**
- * Rate limit by request. Uses Upstash Redis when configured, in-memory otherwise.
- */
-export async function rateLimit(
-  request: NextRequest | Request,
-  config: RateLimitConfig = { limit: 10, window: 60 },
-): Promise<RateLimitResult> {
-  const identifier = config.identifier || getClientIP(request);
-  const limiter = await getUpstashLimiter();
-  if (limiter) return limiter(identifier, config.limit, config.window);
-  return inMemoryLimit(identifier, config.limit, config.window);
-}
-
-/** Alias */
-export const applyRateLimit = rateLimit;
-
-/**
- * Rate limit by an explicit identifier string.
- * Use in Server Actions where no Request object is available.
- */
-export async function rateLimitByIdentifier(
-  identifier: string,
-  config: Omit<RateLimitConfig, "identifier"> = { limit: 60, window: 60 },
-): Promise<RateLimitResult> {
-  const limiter = await getUpstashLimiter();
-  if (limiter) return limiter(identifier, config.limit, config.window);
-  return inMemoryLimit(identifier, config.limit, config.window);
-}
-
-/** Presets for common scenarios */
-export const RateLimitPresets = {
-  STRICT: { limit: 5, window: 60 },
-  AUTH: { limit: 10, window: 60 },
-  API: { limit: 60, window: 60 },
-  GENEROUS: { limit: 100, window: 60 },
-  PASSWORD_RESET: { limit: 3, window: 3600 },
-  EMAIL_VERIFICATION: { limit: 5, window: 3600 },
-} as const;
-
-/** For testing only: clear the in-memory store. */
-export function clearRateLimitStore(): void {
-  memStore.clear();
-}

package/src/security/rbac/Can.tsx

@@ -1,50 +0,0 @@
-// appkit/src/security/rbac/Can.tsx
-"use client";
-
-import React from "react";
-import type { Permission } from "./types";
-import type { RbacHookReturn } from "./hook";
-
-interface CanProps {
-  /** Single required permission */
-  permission?: Permission;
-  /** Multiple permissions to check */
-  permissions?: Permission[];
-  /** When multiple permissions are provided: "all" (default) or "any" */
-  mode?: "all" | "any";
-  /** Rendered when the check fails */
-  fallback?: React.ReactNode;
-  children: React.ReactNode;
-  /** The resolved rbac hook return value — pass from useRBAC() */
-  rbac: Pick<RbacHookReturn, "can" | "canAll" | "canAny">;
-}
-
-/**
- * Conditionally renders children based on RBAC permissions.
- *
- * The consumer's `useRBAC()` hook must be called in the parent component and
- * passed as the `rbac` prop; this avoids coupling `<Can>` to a specific context.
- *
- * @example
- * const rbac = useRBAC();
- * <Can rbac={rbac} permission="admin:payouts"><PayoutsTable /></Can>
- * <Can rbac={rbac} permissions={["seller:products:write", "seller:store"]} mode="any">
- *   <SellerActions />
- * </Can>
- */
-export function Can({
-  permission,
-  permissions,
-  mode = "all",
-  fallback = null,
-  children,
-  rbac,
-}: CanProps): React.ReactElement | null {
-  const allowed = permission
-    ? rbac.can(permission)
-    : mode === "all"
-      ? rbac.canAll(permissions ?? [])
-      : rbac.canAny(permissions ?? []);
-
-  return allowed ? <>{children}</> : <>{fallback}</>;
-}

package/src/security/rbac/default-roles.ts

@@ -1,86 +0,0 @@
-// appkit/src/security/rbac/default-roles.ts
-import type { RoleDefinition } from "./types";
-
-export const DEFAULT_ROLES: Record<string, RoleDefinition> = {
-  super_admin: {
-    label: "Super Admin",
-    permissions: ["*"],
-    inherits: [],
-  },
-  admin: {
-    label: "Admin",
-    permissions: [
-      "admin:access",
-      "admin:settings",
-      "admin:users",
-      "admin:orders",
-      "admin:orders:refund",
-      "admin:products",
-      "admin:reviews",
-      "admin:analytics",
-      "admin:activity",
-      "admin:sessions",
-      "admin:newsletter",
-      "admin:search",
-      "admin:feature-flags",
-      "admin:cms",
-      "admin:payouts",
-      "admin:kyc",
-    ],
-    inherits: ["moderator"],
-  },
-  moderator: {
-    label: "Moderator",
-    permissions: [
-      "admin:access",
-      "admin:reviews",
-      "admin:products",
-      "content:reviews:moderate",
-      "content:products:moderate",
-      "content:orders:support",
-    ],
-    inherits: [],
-  },
-  seller: {
-    label: "Seller",
-    permissions: [
-      "seller:access",
-      "seller:products:read",
-      "seller:products:write",
-      "seller:products:delete",
-      "seller:orders:read",
-      "seller:orders:fulfill",
-      "seller:analytics",
-      "seller:coupons",
-      "seller:store",
-      "seller:payouts:read",
-      "seller:shipping",
-    ],
-    inherits: ["user"],
-  },
-  user: {
-    label: "User",
-    permissions: [
-      "user:profile",
-      "user:orders",
-      "user:orders:cancel",
-      "user:reviews",
-      "user:wishlist",
-      "user:addresses",
-      "user:chat",
-      "user:offers",
-      "user:auctions",
-    ],
-    inherits: [],
-  },
-  support_agent: {
-    label: "Support Agent",
-    permissions: [
-      "admin:access",
-      "admin:orders",
-      "content:orders:support",
-      "admin:users",
-    ],
-    inherits: [],
-  },
-};

package/src/security/rbac/hook.ts

@@ -1,55 +0,0 @@
-// appkit/src/security/rbac/hook.ts
-"use client";
-
-import { useMemo } from "react";
-import type { RbacConfig, Permission } from "./types";
-import {
-  resolvePermissions,
-  hasPermission,
-  hasAllPermissions,
-  hasAnyPermission,
-} from "./resolver";
-
-export interface RbacHookReturn {
-  can: (permission: Permission) => boolean;
-  canAll: (permissions: Permission[]) => boolean;
-  canAny: (permissions: Permission[]) => boolean;
-  roles: string[];
-  permissions: Set<Permission>;
-  isAdmin: boolean;
-  isSeller: boolean;
-}
-
-/**
- * Factory that creates a typed `useRBAC` hook bound to the given config.
- *
- * @example
- * // src/hooks/useRBAC.ts
- * import { createRbacHook } from "@mohasinac/appkit/security";
- * import { RBAC_CONFIG } from "@/constants/rbac";
- * export const useRBAC = createRbacHook(RBAC_CONFIG);
- */
-export function createRbacHook(
-  config: RbacConfig,
-  getUserRoles: () => string[] | null | undefined,
-): () => RbacHookReturn {
-  return function useRBAC(): RbacHookReturn {
-    const userRoles = getUserRoles() ?? [];
-
-    const permissions = useMemo(
-      () => resolvePermissions(userRoles, config),
-      // eslint-disable-next-line react-hooks/exhaustive-deps
-      [userRoles.join(",")],
-    );
-
-    return {
-      can: (permission: Permission) => hasPermission(permissions, permission),
-      canAll: (perms: Permission[]) => hasAllPermissions(permissions, perms),
-      canAny: (perms: Permission[]) => hasAnyPermission(permissions, perms),
-      roles: userRoles,
-      permissions,
-      isAdmin: hasPermission(permissions, "admin:access"),
-      isSeller: hasPermission(permissions, "seller:access"),
-    };
-  };
-}

package/src/security/rbac/index.ts

@@ -1,14 +0,0 @@
-// appkit/src/security/rbac/index.ts
-export type { Permission, RoleDefinition, RbacConfig, ResolvedUser } from "./types";
-export { DEFAULT_ROLES } from "./default-roles";
-export {
-  resolvePermissions,
-  hasPermission,
-  hasAllPermissions,
-  hasAnyPermission,
-} from "./resolver";
-export type { RbacHookReturn } from "./hook";
-export { createRbacHook } from "./hook";
-export { Can } from "./Can";
-export { createRequirePermission, createRequirePermissionSync } from "./server";
-export { createRbacMiddleware } from "./middleware";