hazo_auth 0.3.0 → 1.0.1

package/src/components/ui/alert-dialog.tsx

@@ -0,0 +1,141 @@
+"use client"
+
+import * as React from "react"
+import * as AlertDialogPrimitive from "@radix-ui/react-alert-dialog"
+
+import { cn } from "@/lib/utils"
+import { buttonVariants } from "@/components/ui/button"
+
+const AlertDialog = AlertDialogPrimitive.Root
+
+const AlertDialogTrigger = AlertDialogPrimitive.Trigger
+
+const AlertDialogPortal = AlertDialogPrimitive.Portal
+
+const AlertDialogOverlay = React.forwardRef<
+  React.ElementRef<typeof AlertDialogPrimitive.Overlay>,
+  React.ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Overlay>
+>(({ className, ...props }, ref) => (
+  <AlertDialogPrimitive.Overlay
+    className={cn(
+      "fixed inset-0 z-50 bg-black/80 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
+      className
+    )}
+    {...props}
+    ref={ref}
+  />
+))
+AlertDialogOverlay.displayName = AlertDialogPrimitive.Overlay.displayName
+
+const AlertDialogContent = React.forwardRef<
+  React.ElementRef<typeof AlertDialogPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Content>
+>(({ className, ...props }, ref) => (
+  <AlertDialogPortal>
+    <AlertDialogOverlay />
+    <AlertDialogPrimitive.Content
+      ref={ref}
+      className={cn(
+        "fixed left-[50%] top-[50%] z-50 grid w-full max-w-lg translate-x-[-50%] translate-y-[-50%] gap-4 border bg-background p-6 shadow-lg duration-200 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[state=closed]:slide-out-to-left-1/2 data-[state=closed]:slide-out-to-top-[48%] data-[state=open]:slide-in-from-left-1/2 data-[state=open]:slide-in-from-top-[48%] sm:rounded-lg",
+        className
+      )}
+      {...props}
+    />
+  </AlertDialogPortal>
+))
+AlertDialogContent.displayName = AlertDialogPrimitive.Content.displayName
+
+const AlertDialogHeader = ({
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLDivElement>) => (
+  <div
+    className={cn(
+      "flex flex-col space-y-2 text-center sm:text-left",
+      className
+    )}
+    {...props}
+  />
+)
+AlertDialogHeader.displayName = "AlertDialogHeader"
+
+const AlertDialogFooter = ({
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLDivElement>) => (
+  <div
+    className={cn(
+      "flex flex-col-reverse sm:flex-row sm:justify-end sm:space-x-2",
+      className
+    )}
+    {...props}
+  />
+)
+AlertDialogFooter.displayName = "AlertDialogFooter"
+
+const AlertDialogTitle = React.forwardRef<
+  React.ElementRef<typeof AlertDialogPrimitive.Title>,
+  React.ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Title>
+>(({ className, ...props }, ref) => (
+  <AlertDialogPrimitive.Title
+    ref={ref}
+    className={cn("text-lg font-semibold", className)}
+    {...props}
+  />
+))
+AlertDialogTitle.displayName = AlertDialogPrimitive.Title.displayName
+
+const AlertDialogDescription = React.forwardRef<
+  React.ElementRef<typeof AlertDialogPrimitive.Description>,
+  React.ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Description>
+>(({ className, ...props }, ref) => (
+  <AlertDialogPrimitive.Description
+    ref={ref}
+    className={cn("text-sm text-muted-foreground", className)}
+    {...props}
+  />
+))
+AlertDialogDescription.displayName =
+  AlertDialogPrimitive.Description.displayName
+
+const AlertDialogAction = React.forwardRef<
+  React.ElementRef<typeof AlertDialogPrimitive.Action>,
+  React.ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Action>
+>(({ className, ...props }, ref) => (
+  <AlertDialogPrimitive.Action
+    ref={ref}
+    className={cn(buttonVariants(), className)}
+    {...props}
+  />
+))
+AlertDialogAction.displayName = AlertDialogPrimitive.Action.displayName
+
+const AlertDialogCancel = React.forwardRef<
+  React.ElementRef<typeof AlertDialogPrimitive.Cancel>,
+  React.ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Cancel>
+>(({ className, ...props }, ref) => (
+  <AlertDialogPrimitive.Cancel
+    ref={ref}
+    className={cn(
+      buttonVariants({ variant: "outline" }),
+      "mt-2 sm:mt-0",
+      className
+    )}
+    {...props}
+  />
+))
+AlertDialogCancel.displayName = AlertDialogPrimitive.Cancel.displayName
+
+export {
+  AlertDialog,
+  AlertDialogPortal,
+  AlertDialogOverlay,
+  AlertDialogTrigger,
+  AlertDialogContent,
+  AlertDialogHeader,
+  AlertDialogFooter,
+  AlertDialogTitle,
+  AlertDialogDescription,
+  AlertDialogAction,
+  AlertDialogCancel,
+}

package/src/components/ui/checkbox.tsx

@@ -0,0 +1,30 @@
+"use client"
+
+import * as React from "react"
+import * as CheckboxPrimitive from "@radix-ui/react-checkbox"
+import { Check } from "lucide-react"
+
+import { cn } from "@/lib/utils"
+
+const Checkbox = React.forwardRef<
+  React.ElementRef<typeof CheckboxPrimitive.Root>,
+  React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>
+>(({ className, ...props }, ref) => (
+  <CheckboxPrimitive.Root
+    ref={ref}
+    className={cn(
+      "grid place-content-center peer h-4 w-4 shrink-0 rounded-sm border border-primary shadow focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:bg-primary data-[state=checked]:text-primary-foreground",
+      className
+    )}
+    {...props}
+  >
+    <CheckboxPrimitive.Indicator
+      className={cn("grid place-content-center text-current")}
+    >
+      <Check className="h-4 w-4" />
+    </CheckboxPrimitive.Indicator>
+  </CheckboxPrimitive.Root>
+))
+Checkbox.displayName = CheckboxPrimitive.Root.displayName
+
+export { Checkbox }

package/src/components/ui/table.tsx

@@ -0,0 +1,120 @@
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+
+const Table = React.forwardRef<
+  HTMLTableElement,
+  React.HTMLAttributes<HTMLTableElement>
+>(({ className, ...props }, ref) => (
+  <div className="relative w-full overflow-auto">
+    <table
+      ref={ref}
+      className={cn("w-full caption-bottom text-sm", className)}
+      {...props}
+    />
+  </div>
+))
+Table.displayName = "Table"
+
+const TableHeader = React.forwardRef<
+  HTMLTableSectionElement,
+  React.HTMLAttributes<HTMLTableSectionElement>
+>(({ className, ...props }, ref) => (
+  <thead ref={ref} className={cn("[&_tr]:border-b", className)} {...props} />
+))
+TableHeader.displayName = "TableHeader"
+
+const TableBody = React.forwardRef<
+  HTMLTableSectionElement,
+  React.HTMLAttributes<HTMLTableSectionElement>
+>(({ className, ...props }, ref) => (
+  <tbody
+    ref={ref}
+    className={cn("[&_tr:last-child]:border-0", className)}
+    {...props}
+  />
+))
+TableBody.displayName = "TableBody"
+
+const TableFooter = React.forwardRef<
+  HTMLTableSectionElement,
+  React.HTMLAttributes<HTMLTableSectionElement>
+>(({ className, ...props }, ref) => (
+  <tfoot
+    ref={ref}
+    className={cn(
+      "border-t bg-muted/50 font-medium [&>tr]:last:border-b-0",
+      className
+    )}
+    {...props}
+  />
+))
+TableFooter.displayName = "TableFooter"
+
+const TableRow = React.forwardRef<
+  HTMLTableRowElement,
+  React.HTMLAttributes<HTMLTableRowElement>
+>(({ className, ...props }, ref) => (
+  <tr
+    ref={ref}
+    className={cn(
+      "border-b transition-colors hover:bg-muted/50 data-[state=selected]:bg-muted",
+      className
+    )}
+    {...props}
+  />
+))
+TableRow.displayName = "TableRow"
+
+const TableHead = React.forwardRef<
+  HTMLTableCellElement,
+  React.ThHTMLAttributes<HTMLTableCellElement>
+>(({ className, ...props }, ref) => (
+  <th
+    ref={ref}
+    className={cn(
+      "h-10 px-2 text-left align-middle font-medium text-muted-foreground [&:has([role=checkbox])]:pr-0 [&>[role=checkbox]]:translate-y-[2px]",
+      className
+    )}
+    {...props}
+  />
+))
+TableHead.displayName = "TableHead"
+
+const TableCell = React.forwardRef<
+  HTMLTableCellElement,
+  React.TdHTMLAttributes<HTMLTableCellElement>
+>(({ className, ...props }, ref) => (
+  <td
+    ref={ref}
+    className={cn(
+      "p-2 align-middle [&:has([role=checkbox])]:pr-0 [&>[role=checkbox]]:translate-y-[2px]",
+      className
+    )}
+    {...props}
+  />
+))
+TableCell.displayName = "TableCell"
+
+const TableCaption = React.forwardRef<
+  HTMLTableCaptionElement,
+  React.HTMLAttributes<HTMLTableCaptionElement>
+>(({ className, ...props }, ref) => (
+  <caption
+    ref={ref}
+    className={cn("mt-4 text-sm text-muted-foreground", className)}
+    {...props}
+  />
+))
+TableCaption.displayName = "TableCaption"
+
+export {
+  Table,
+  TableHeader,
+  TableBody,
+  TableFooter,
+  TableHead,
+  TableRow,
+  TableCell,
+  TableCaption,
+}

package/src/lib/auth/auth_cache.ts

@@ -0,0 +1,220 @@
+// file_description: LRU cache implementation for hazo_get_auth with TTL and size limits
+// section: imports
+import type { HazoAuthUser } from "./auth_types";
+
+// section: types
+
+/**
+ * Cache entry structure
+ */
+type CacheEntry = {
+  user: HazoAuthUser;
+  permissions: string[];
+  role_ids: number[];
+  timestamp: number; // Unix timestamp in milliseconds
+  cache_version: number; // Version number for smart invalidation
+};
+
+/**
+ * LRU cache implementation with TTL and size limits
+ * Uses Map to maintain insertion order for LRU eviction
+ */
+class AuthCache {
+  private cache: Map<string, CacheEntry>;
+  private max_size: number;
+  private ttl_ms: number;
+  private max_age_ms: number;
+  private role_version_map: Map<number, number>; // Track version per role for smart invalidation
+
+  constructor(
+    max_size: number,
+    ttl_minutes: number,
+    max_age_minutes: number,
+  ) {
+    this.cache = new Map();
+    this.max_size = max_size;
+    this.ttl_ms = ttl_minutes * 60 * 1000;
+    this.max_age_ms = max_age_minutes * 60 * 1000;
+    this.role_version_map = new Map();
+  }
+
+  /**
+   * Gets a cache entry for a user
+   * Returns undefined if not found, expired, or too old
+   * @param user_id - User ID to look up
+   * @returns Cache entry or undefined
+   */
+  get(user_id: string): CacheEntry | undefined {
+    const entry = this.cache.get(user_id);
+
+    if (!entry) {
+      return undefined;
+    }
+
+    const now = Date.now();
+    const age = now - entry.timestamp;
+
+    // Check if entry is expired (TTL)
+    if (age > this.ttl_ms) {
+      this.cache.delete(user_id);
+      return undefined;
+    }
+
+    // Check if entry is too old (force refresh threshold)
+    if (age > this.max_age_ms) {
+      // Don't delete, but mark as stale so caller can refresh
+      // Return undefined to force refresh
+      this.cache.delete(user_id);
+      return undefined;
+    }
+
+    // Move to end (most recently used)
+    this.cache.delete(user_id);
+    this.cache.set(user_id, entry);
+
+    return entry;
+  }
+
+  /**
+   * Sets a cache entry for a user
+   * Evicts least recently used entries if cache is full
+   * @param user_id - User ID
+   * @param user - User data
+   * @param permissions - User permissions
+   * @param role_ids - User role IDs
+   */
+  set(
+    user_id: string,
+    user: HazoAuthUser,
+    permissions: string[],
+    role_ids: number[],
+  ): void {
+    // Evict LRU entries if cache is full
+    while (this.cache.size >= this.max_size) {
+      const first_key = this.cache.keys().next().value;
+      if (first_key) {
+        this.cache.delete(first_key);
+      } else {
+        break;
+      }
+    }
+
+    // Get current cache version for user's roles
+    const cache_version = this.get_max_role_version(role_ids);
+
+    const entry: CacheEntry = {
+      user,
+      permissions,
+      role_ids,
+      timestamp: Date.now(),
+      cache_version,
+    };
+
+    this.cache.set(user_id, entry);
+  }
+
+  /**
+   * Invalidates cache for a specific user
+   * @param user_id - User ID to invalidate
+   */
+  invalidate_user(user_id: string): void {
+    this.cache.delete(user_id);
+  }
+
+  /**
+   * Invalidates cache for all users with specific roles
+   * Uses cache version to determine if invalidation is needed
+   * @param role_ids - Array of role IDs to invalidate
+   */
+  invalidate_by_roles(role_ids: number[]): void {
+    // Increment version for affected roles
+    for (const role_id of role_ids) {
+      const current_version = this.role_version_map.get(role_id) || 0;
+      this.role_version_map.set(role_id, current_version + 1);
+    }
+
+    // Remove entries where cache version is older than role version
+    const entries_to_remove: string[] = [];
+    for (const [user_id, entry] of this.cache.entries()) {
+      const max_role_version = this.get_max_role_version(entry.role_ids);
+      if (max_role_version > entry.cache_version) {
+        entries_to_remove.push(user_id);
+      }
+    }
+
+    for (const user_id of entries_to_remove) {
+      this.cache.delete(user_id);
+    }
+  }
+
+  /**
+   * Invalidates all cache entries
+   */
+  invalidate_all(): void {
+    this.cache.clear();
+  }
+
+  /**
+   * Gets the maximum cache version for a set of roles
+   * Used to determine if cache entry is stale
+   * @param role_ids - Array of role IDs
+   * @returns Maximum version number
+   */
+  private get_max_role_version(role_ids: number[]): number {
+    if (role_ids.length === 0) {
+      return 0;
+    }
+
+    let max_version = 0;
+    for (const role_id of role_ids) {
+      const version = this.role_version_map.get(role_id) || 0;
+      max_version = Math.max(max_version, version);
+    }
+
+    return max_version;
+  }
+
+  /**
+   * Gets cache statistics
+   * @returns Object with cache size, max size, and hit rate estimate
+   */
+  get_stats(): {
+    size: number;
+    max_size: number;
+  } {
+    return {
+      size: this.cache.size,
+      max_size: this.max_size,
+    };
+  }
+}
+
+// section: singleton
+// Global cache instance (initialized with defaults, will be configured on first use)
+let auth_cache_instance: AuthCache | null = null;
+
+/**
+ * Gets or creates the global auth cache instance
+ * @param max_size - Maximum cache size (default: 10000)
+ * @param ttl_minutes - TTL in minutes (default: 15)
+ * @param max_age_minutes - Max age in minutes (default: 30)
+ * @returns Auth cache instance
+ */
+export function get_auth_cache(
+  max_size: number = 10000,
+  ttl_minutes: number = 15,
+  max_age_minutes: number = 30,
+): AuthCache {
+  if (!auth_cache_instance) {
+    auth_cache_instance = new AuthCache(max_size, ttl_minutes, max_age_minutes);
+  }
+  return auth_cache_instance;
+}
+
+/**
+ * Resets the global cache instance (useful for testing)
+ */
+export function reset_auth_cache(): void {
+  auth_cache_instance = null;
+}
+

package/src/lib/auth/auth_rate_limiter.ts

@@ -0,0 +1,121 @@
+// file_description: Simple in-memory rate limiter for hazo_get_auth API endpoint
+// section: types
+
+/**
+ * Rate limit entry structure
+ */
+type RateLimitEntry = {
+  count: number;
+  window_start: number; // Unix timestamp in milliseconds
+};
+
+/**
+ * Simple in-memory rate limiter
+ * Tracks request counts per key within a time window
+ */
+class RateLimiter {
+  private limits: Map<string, RateLimitEntry>;
+  private window_ms: number; // 1 minute = 60000ms
+
+  constructor() {
+    this.limits = new Map();
+    this.window_ms = 60 * 1000; // 1 minute window
+  }
+
+  /**
+   * Checks if a request should be allowed
+   * @param key - Rate limit key (e.g., "user:123" or "ip:192.168.1.1")
+   * @param max_requests - Maximum requests allowed per window
+   * @returns true if allowed, false if rate limited
+   */
+  check(key: string, max_requests: number): boolean {
+    const now = Date.now();
+    const entry = this.limits.get(key);
+
+    if (!entry) {
+      // First request for this key
+      this.limits.set(key, {
+        count: 1,
+        window_start: now,
+      });
+      return true;
+    }
+
+    // Check if window has expired
+    if (now - entry.window_start >= this.window_ms) {
+      // Reset window
+      this.limits.set(key, {
+        count: 1,
+        window_start: now,
+      });
+      return true;
+    }
+
+    // Check if limit exceeded
+    if (entry.count >= max_requests) {
+      return false;
+    }
+
+    // Increment count
+    entry.count++;
+    return true;
+  }
+
+  /**
+   * Cleans up old entries (call periodically to prevent memory leak)
+   * Removes entries older than 2 windows
+   */
+  cleanup(): void {
+    const now = Date.now();
+    const cutoff = now - 2 * this.window_ms;
+
+    const keys_to_delete: string[] = [];
+    for (const [key, entry] of this.limits.entries()) {
+      if (entry.window_start < cutoff) {
+        keys_to_delete.push(key);
+      }
+    }
+
+    for (const key of keys_to_delete) {
+      this.limits.delete(key);
+    }
+  }
+
+  /**
+   * Gets rate limit statistics
+   * @returns Object with current limit entries count
+   */
+  get_stats(): { active_limits: number } {
+    return {
+      active_limits: this.limits.size,
+    };
+  }
+}
+
+// section: singleton
+// Global rate limiter instance
+let rate_limiter_instance: RateLimiter | null = null;
+
+/**
+ * Gets or creates the global rate limiter instance
+ * @returns Rate limiter instance
+ */
+export function get_rate_limiter(): RateLimiter {
+  if (!rate_limiter_instance) {
+    rate_limiter_instance = new RateLimiter();
+
+    // Cleanup old entries every 5 minutes
+    setInterval(() => {
+      rate_limiter_instance?.cleanup();
+    }, 5 * 60 * 1000);
+  }
+  return rate_limiter_instance;
+}
+
+/**
+ * Resets the global rate limiter instance (useful for testing)
+ */
+export function reset_rate_limiter(): void {
+  rate_limiter_instance = null;
+}
+

package/src/lib/auth/auth_types.ts

@@ -0,0 +1,65 @@
+// file_description: Type definitions and error classes for hazo_get_auth utility
+// section: types
+
+/**
+ * User data structure returned by hazo_get_auth
+ */
+export type HazoAuthUser = {
+  id: string;
+  name: string | null;
+  email_address: string;
+  is_active: boolean;
+  profile_picture_url: string | null;
+};
+
+/**
+ * Result type for hazo_get_auth function
+ * Returns authenticated state with user data and permissions, or unauthenticated state
+ */
+export type HazoAuthResult =
+  | {
+      authenticated: true;
+      user: HazoAuthUser;
+      permissions: string[];
+      permission_ok: boolean;
+      missing_permissions?: string[];
+    }
+  | {
+      authenticated: false;
+      user: null;
+      permissions: [];
+      permission_ok: false;
+    };
+
+/**
+ * Options for hazo_get_auth function
+ */
+export type HazoAuthOptions = {
+  /**
+   * Array of required permissions to check
+   * If provided, permission_ok will be set based on whether user has all required permissions
+   */
+  required_permissions?: string[];
+  /**
+   * If true, throws PermissionError when user lacks required permissions
+   * If false (default), returns permission_ok: false without throwing
+   */
+  strict?: boolean;
+};
+
+/**
+ * Custom error class for permission denials
+ * Includes technical and user-friendly error messages
+ */
+export class PermissionError extends Error {
+  constructor(
+    public missing_permissions: string[],
+    public user_permissions: string[],
+    public required_permissions: string[],
+    public user_friendly_message?: string,
+  ) {
+    super(`Missing permissions: ${missing_permissions.join(", ")}`);
+    this.name = "PermissionError";
+  }
+}
+