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/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');
+  }
+}