Initial commit: Port Nimara CRM (Layers 0-4)

Full CRM rebuild with Next.js 15, TypeScript, Tailwind, Drizzle ORM,
PostgreSQL, Redis, BullMQ, MinIO, and Socket.io. Includes 461 source
files covering clients, berths, interests/pipeline, documents/EOI,
expenses/invoices, email, notifications, dashboard, admin, and
client portal. CI/CD via Gitea Actions with Docker builds.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

src/lib/auth/client.ts

@@ -0,0 +1,9 @@
+'use client';
+
+import { createAuthClient } from 'better-auth/react';
+
+export const authClient = createAuthClient({
+  baseURL: process.env.NEXT_PUBLIC_APP_URL,
+});
+
+export const { useSession, signIn, signOut, getSession } = authClient;

src/lib/auth/index.ts

@@ -0,0 +1,53 @@
+import { betterAuth } from 'better-auth';
+import { drizzleAdapter } from 'better-auth/adapters/drizzle';
+
+import { db } from '@/lib/db';
+import { logger } from '@/lib/logger';
+
+/**
+ * Better Auth server configuration.
+ *
+ * Sessions are stored in PostgreSQL (not Redis) per SECURITY-GUIDELINES.md §1.2.
+ * The drizzle adapter handles session persistence via the existing `sessions` table.
+ */
+export const auth = betterAuth({
+  database: drizzleAdapter(db, {
+    provider: 'pg',
+  }),
+
+  emailAndPassword: {
+    enabled: true,
+    minPasswordLength: 12,
+    // Accounts are admin-created only — no self-service email verification flow.
+    requireEmailVerification: false,
+  },
+
+  session: {
+    // Enable cookie-level session caching to reduce DB reads (5-minute cache).
+    cookieCache: {
+      enabled: true,
+      maxAge: 5 * 60,
+    },
+    // Absolute session lifetime: 24 hours.
+    expiresIn: 60 * 60 * 24,
+    // Refresh the session whenever the user is active in the last 25% of its lifetime (6h).
+    updateAge: 60 * 60 * 6,
+  },
+
+  advanced: {
+    cookiePrefix: 'pn-crm',
+    defaultCookieAttributes: {
+      httpOnly: true,
+      secure: process.env.NODE_ENV === 'production',
+      sameSite: 'strict' as const,
+    },
+  },
+
+  logger: {
+    disabled: false,
+    level: 'error' as const,
+  },
+});
+
+export type Session = typeof auth.$Infer.Session;
+export type User = typeof auth.$Infer.Session.user;

src/lib/auth/permissions.ts

@@ -0,0 +1,50 @@
+import { ForbiddenError } from '@/lib/errors';
+import { type RolePermissions } from '@/lib/db/schema/users';
+import type { AuthContext } from '@/lib/api/helpers';
+
+export type { RolePermissions };
+
+export type PermissionResource = keyof RolePermissions;
+export type PermissionAction<R extends PermissionResource> = keyof RolePermissions[R];
+
+/**
+ * Checks whether a permissions map grants a specific resource/action pair.
+ *
+ * Returns `true` automatically when `permissions` is `null`, which signals a
+ * super-admin context that bypasses all permission checks.
+ */
+export function hasPermission<R extends PermissionResource>(
+  permissions: RolePermissions | null,
+  resource: R,
+  action: PermissionAction<R>,
+): boolean {
+  // null = super admin; all permissions implicitly granted.
+  if (permissions === null) return true;
+
+  const resourcePerms = permissions[resource] as Record<string, boolean> | undefined;
+  if (!resourcePerms) return false;
+
+  return resourcePerms[action as string] === true;
+}
+
+/**
+ * Throws a `ForbiddenError` if the auth context does not have the required
+ * resource/action permission.
+ *
+ * For use inside API route handlers or service functions after `withAuth` has
+ * resolved the context.
+ *
+ * @example
+ * requirePermission(ctx, 'clients', 'delete');
+ */
+export function requirePermission<R extends PermissionResource>(
+  ctx: Pick<AuthContext, 'isSuperAdmin' | 'permissions'>,
+  resource: R,
+  action: PermissionAction<R>,
+): void {
+  if (ctx.isSuperAdmin) return;
+
+  if (!hasPermission(ctx.permissions, resource, action)) {
+    throw new ForbiddenError('Insufficient permissions');
+  }
+}