nuxt-auto-crud 1.3.0 → 1.5.0

package/README.md

@@ -1,11 +1,8 @@
 # Nuxt Auto CRUD
 
-[![npm version][npm-version-src]][npm-version-href]
-[![npm downloads][npm-downloads-src]][npm-downloads-href]
-[![License][license-src]][license-href]
-[![Nuxt][nuxt-src]][nuxt-href]
+> **Note:** This module is currently in its alpha stage. However, you can use it to accelerate MVP development. It has not been tested thoroughly enough for production use; only happy-path testing is performed for each release.
 
-Auto-generate RESTful CRUD APIs for your **Nuxt** application based solely on your database schema. No configuration needed!
+Auto-generate RESTful CRUD APIs for your **Nuxt** application based solely on your database schema. Minimal configuration required.
 
 - [✨ Release Notes](/CHANGELOG.md)
 - [🎮 Try the Playground](/playground)
@@ -20,39 +17,39 @@ Auto-generate RESTful CRUD APIs for your **Nuxt** application based solely on yo
 
 ## 📦 How to install
 
-### New Project (Recommended)
+### 1. Fullstack Template (Recommended)
 
 Start a new project with everything pre-configured using our template:
 
 ```bash
 npx nuxi init -t gh:clifordpereira/nuxt-auto-crud_template <project-name>
 cd <project-name>
+bun install
 bun db:generate
 bun run dev
 ```
 
-### Add User
-Open Nuxt DevTools (bottom-middle icon) > `...` menu > **Database** icon to add users.
-    > **Note:** If the users table doesn't appear, restart the server (`Ctrl + C` and `bun run dev`).
-
-That's it! You can now access the APIs:
+Detailed instructions can be found in [https://auto-crud.clifland.in/](https://auto-crud.clifland.in/)
 
-### Test API
-Visit [http://localhost:3000/api/users](http://localhost:3000/api/users).
-
-### Existing Project
+### 2. Manual Setup (Existing Project)
 
 If you want to add `nuxt-auto-crud` to an existing project, follow these steps:
 
-### 1. Install dependencies
+> **Note:** These instructions assume you are using NuxtHub. If you are using a custom SQLite setup (e.g. better-sqlite3, Turso), please see [Custom Setup](./custom-setup.md).
+
+#### Install dependencies
 
 ```bash
 # Install module and required dependencies
+npm install nuxt-auto-crud @nuxthub/core@latest drizzle-orm
+npm install --save-dev wrangler drizzle-kit
+
+# Or using bun
 bun add nuxt-auto-crud @nuxthub/core@latest drizzle-orm
 bun add --dev wrangler drizzle-kit
 ```
 
-### 2. Configure Nuxt
+#### Configure Nuxt
 
 Add the modules to your `nuxt.config.ts`:
 
@@ -67,11 +64,12 @@ export default defineNuxtConfig({
 
   autoCrud: {
     schemaPath: 'server/database/schema', // default value
+    auth: false, // Disable auth by default for easy testing
   },
 })
 ```
 
-### 3. Configure Drizzle
+#### Configure Drizzle
 
 Add the generation script to your `package.json`:
 
@@ -96,7 +94,7 @@ export default defineConfig({
 })
 ```
 
-### 4. Setup Database Connection
+#### Setup Database Connection
 
 Create `server/utils/drizzle.ts` to export the database instance:
 
@@ -116,7 +114,7 @@ export function useDrizzle() {
 export type User = typeof schema.users.$inferSelect
 ```
 
-### 5. Define your database schema
+#### Define your database schema
 
 Create `server/database/schema.ts`:
 
@@ -134,7 +132,7 @@ export const users = sqliteTable('users', {
 })
 ```
 
-### 6. Run the project
+#### Run the project
 
 ```bash
 cd <project-name>
@@ -142,15 +140,82 @@ bun db:generate
 bun run dev
 ```
 
-That's it! 🎉 Your CRUD APIs are now available:
+That's it! 🎉 Your CRUD APIs are now available at `/api/users`.
+
+### 3. Backend-only App (API Mode)
+
+If you are using Nuxt as a backend for a separate client application (e.g., mobile app, SPA), you can use this module to quickly generate REST APIs.
+
+In this case, you might handle authentication differently (e.g., validating tokens in middleware) or disable the built-in auth checks if you have a global auth middleware.
+
+```ts
+export default defineNuxtConfig({
+  modules: ['nuxt-auto-crud'],
+  autoCrud: {
+    auth: false // APIs are public (or handled by your own middleware)
+  }
+})
+```
+
+## 🔐 Authentication Configuration
+
+The module supports `auth: false` by default, which exposes all LCRUD APIs. You can enable authentication and authorization as needed.
+
+### Session Auth (Default)
+
+Requires `nuxt-auth-utils` and `nuxt-authorization`.
+
+```typescript
+export default defineNuxtConfig({
+  autoCrud: {
+    auth: {
+      type: 'session',
+      authentication: true, // Enables requireUserSession() check
+      authorization: true // Enables authorize(model, action) check
+    }
+  }
+})
+```
+
+### JWT Auth
 
-- `GET /api/users` - List all users
-- `POST /api/users` - Create a new user
-- `GET /api/users/:id` - Get user by ID
-- `PATCH /api/users/:id` - Update user
-- `DELETE /api/users/:id` - Delete user
+Useful for backend-only apps.
 
-_(Same endpoints for all your tables!)_
+```typescript
+export default defineNuxtConfig({
+  autoCrud: {
+    auth: {
+      type: 'jwt',
+      authentication: true,
+      jwtSecret: process.env.JWT_SECRET,
+      authorization: true
+    }
+  }
+})
+```
+
+## 🛡️ Resource Configuration (RBAC)
+
+You can define fine-grained access control and resource policies using `autocrud.config.ts` in your project root. This file is optional and useful when you need specific rules per resource.
+
+```typescript
+// autocrud.config.ts
+export default {
+  resources: {
+    users: {
+      // Access Control
+      auth: {
+        // Admin has full access
+        admin: true,
+        // Public (unauthenticated) users can only list and read
+        public: ['list', 'read'],
+      },
+      // Field Visibility
+      publicColumns: ['id', 'name', 'avatar'], // Only these columns are returned to public users
+    },
+  }
+}
+```
 
 ## 🎮 Try the Playground
 
@@ -161,17 +226,21 @@ Want to see it in action? Clone this repo and try the playground:
 git clone https://github.com/clifordpereira/nuxt-auto-crud.git
 cd nuxt-auto-crud
 
-# Install dependencies
+# Install dependencies (parent folder)
 bun install
 
-# Run the playground
+# Run the playground (Fullstack)
 cd playground
 bun install
 bun db:generate
 bun run dev
-```
 
-The playground includes a sample schema with users, posts, and comments tables, plus an interactive UI to explore all the features.
+# Run the playground (Backend Only)
+cd playground-backendonly
+bun install
+bun db:generate
+bun run dev
+```
 
 ## 📖 Usage Examples
 
@@ -219,7 +288,7 @@ await $fetch("/api/users/1", {
 });
 ```
 
-## ⚙️ Configuration
+## Configuration
 
 ### Module Options
 
@@ -242,11 +311,21 @@ By default, the following fields are protected from updates:
 
 You can customize updatable fields in your schema by modifying the `modelMapper.ts` utility.
 
+### Hidden Fields
+
+By default, the following fields are hidden from API responses for security:
+
+- `password`
+- `secret`
+- `token`
+
+You can customize hidden fields by modifying the `modelMapper.ts` utility.
+
 ## 🔧 Requirements
 
 - Nuxt 3 or 4
-- NuxtHub (for database functionality)
-- Drizzle ORM
+- Drizzle ORM (SQLite)
+- NuxtHub (Recommended) or [Custom SQLite Setup](./custom-setup.md)
 
 ## 🤝 Contributing
 
@@ -259,5 +338,3 @@ Contributions are welcome! Please check out the [contribution guide](/CONTRIBUTI
 ## 👨‍💻 Author
 
 Made with ❤️ by [Cliford Pereira](https://github.com/clifordpereira)
-
-

package/dist/module.d.mts

@@ -1,7 +1,6 @@
 import * as _nuxt_schema from '@nuxt/schema';
 
 interface ModuleOptions {
-    /**
     /**
      * Path to the database schema file
      * @default 'server/database/schema'
@@ -12,6 +11,59 @@ interface ModuleOptions {
      * @default 'server/utils/drizzle'
      */
     drizzlePath?: string;
+    /**
+     * Authentication configuration
+     */
+    auth?: boolean | AuthOptions;
+    /**
+     * Resource-specific configuration
+     * Define public access and column visibility
+     */
+    resources?: {
+        [modelName: string]: {
+            /**
+             * Actions allowed without authentication
+             * true = all actions
+             * array = specific actions ('list', 'create', 'read', 'update', 'delete')
+             */
+            public?: boolean | ('list' | 'create' | 'read' | 'update' | 'delete')[];
+            /**
+             * Columns to return for unauthenticated requests
+             * If not specified, all columns (except hidden ones) are returned
+             */
+            publicColumns?: string[];
+        };
+    };
+}
+interface AuthOptions {
+    /**
+     * Authentication type
+     * @default 'session'
+     */
+    type?: 'session' | 'jwt';
+    /**
+     * JWT Secret (required if type is 'jwt')
+     */
+    jwtSecret?: string;
+    /**
+     * Enable authentication checks (requires nuxt-auth-utils for session)
+     * @default false
+     */
+    authentication: boolean;
+    /**
+     * Enable authorization checks (requires nuxt-authorization)
+     * @default false
+     */
+    authorization?: boolean;
+}
+interface RuntimeModuleOptions extends Omit<ModuleOptions, 'auth'> {
+    auth: AuthOptions;
+}
+
+declare module '@nuxt/schema' {
+    interface RuntimeConfig {
+        autoCrud: RuntimeModuleOptions;
+    }
 }
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
 

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-auto-crud",
   "configKey": "autoCrud",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -7,9 +7,10 @@ const module$1 = defineNuxtModule({
   },
   defaults: {
     schemaPath: "server/database/schema",
-    drizzlePath: "server/utils/drizzle"
+    drizzlePath: "server/utils/drizzle",
+    auth: false
   },
-  setup(options, nuxt) {
+  async setup(options, nuxt) {
     const resolver = createResolver(import.meta.url);
     const schemaPath = resolver.resolve(
       nuxt.options.rootDir,
@@ -21,6 +22,57 @@ const module$1 = defineNuxtModule({
       options.drizzlePath
     );
     nuxt.options.alias["#site/drizzle"] = drizzlePath;
+    nuxt.options.alias["#authorization"] = nuxt.options.alias["#authorization"] || "nuxt-authorization/utils";
+    const { loadConfig } = await import('c12');
+    const { config: externalConfig } = await loadConfig({
+      name: "autocrud",
+      cwd: nuxt.options.rootDir
+    });
+    let mergedAuth = {
+      authentication: false,
+      authorization: false,
+      type: "session"
+    };
+    if (options.auth === true) {
+      mergedAuth = {
+        authentication: true,
+        authorization: true,
+        type: "session",
+        ...typeof externalConfig?.auth === "object" ? externalConfig.auth : {}
+      };
+    } else if (options.auth === false) {
+      mergedAuth = {
+        authentication: false,
+        authorization: false,
+        type: "session"
+      };
+    } else {
+      mergedAuth = {
+        authentication: true,
+        // Default to true if object provided? Or undefined?
+        // If options.auth is undefined, we might want defaults.
+        // But if defaults say auth: false, then options.auth might be undefined.
+        // Let's stick to the plan: default is false.
+        ...typeof externalConfig?.auth === "object" ? externalConfig.auth : {},
+        ...typeof options.auth === "object" ? options.auth : {}
+      };
+      if (mergedAuth.authentication === void 0) {
+        mergedAuth.authentication = false;
+      }
+    }
+    const mergedResources = {
+      ...externalConfig?.resources,
+      ...options.resources
+    };
+    nuxt.options.runtimeConfig.autoCrud = {
+      auth: {
+        authentication: mergedAuth.authentication ?? false,
+        authorization: mergedAuth.authorization ?? false,
+        type: mergedAuth.type ?? "session",
+        jwtSecret: mergedAuth.jwtSecret
+      },
+      resources: mergedResources || {}
+    };
     const apiDir = resolver.resolve("./runtime/server/api");
     addServerHandler({
       route: "/api/:model",

package/dist/runtime/server/api/[model]/[id].delete.d.ts

@@ -1,2 +1,2 @@
-declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<any>>;
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<Record<string, unknown>>>;
 export default _default;

package/dist/runtime/server/api/[model]/[id].delete.js

@@ -1,9 +1,23 @@
 import { eventHandler, getRouterParams, createError } from "h3";
 import { eq } from "drizzle-orm";
-import { getTableForModel, getModelSingularName } from "../../utils/modelMapper.js";
+import { getTableForModel, getModelSingularName, filterHiddenFields, filterPublicColumns } from "../../utils/modelMapper.js";
 import { useDrizzle } from "#site/drizzle";
+import { useAutoCrudConfig } from "../../utils/config.js";
+import { checkAdminAccess } from "../../utils/auth.js";
 export default eventHandler(async (event) => {
+  const { resources } = useAutoCrudConfig();
   const { model, id } = getRouterParams(event);
+  const isAdmin = await checkAdminAccess(event, model, "delete");
+  if (!isAdmin) {
+    const resourceConfig = resources?.[model];
+    const isPublic = resourceConfig?.public === true || Array.isArray(resourceConfig?.public) && resourceConfig.public.includes("delete");
+    if (!isPublic) {
+      throw createError({
+        statusCode: 401,
+        message: "Unauthorized"
+      });
+    }
+  }
   const table = getTableForModel(model);
   const singularName = getModelSingularName(model);
   const deletedRecord = await useDrizzle().delete(table).where(eq(table.id, Number(id))).returning().get();
@@ -13,5 +27,9 @@ export default eventHandler(async (event) => {
       message: `${singularName} not found`
     });
   }
-  return deletedRecord;
+  if (isAdmin) {
+    return filterHiddenFields(model, deletedRecord);
+  } else {
+    return filterPublicColumns(model, deletedRecord);
+  }
 });

package/dist/runtime/server/api/[model]/[id].get.d.ts

@@ -1,2 +1,2 @@
-declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<any>>;
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<Record<string, unknown>>>;
 export default _default;

package/dist/runtime/server/api/[model]/[id].get.js

@@ -1,17 +1,34 @@
 import { eventHandler, getRouterParams, createError } from "h3";
 import { eq } from "drizzle-orm";
-import { getTableForModel, getModelSingularName } from "../../utils/modelMapper.js";
+import { getTableForModel, filterHiddenFields, filterPublicColumns } from "../../utils/modelMapper.js";
 import { useDrizzle } from "#site/drizzle";
+import { useAutoCrudConfig } from "../../utils/config.js";
+import { checkAdminAccess } from "../../utils/auth.js";
 export default eventHandler(async (event) => {
+  const { resources } = useAutoCrudConfig();
   const { model, id } = getRouterParams(event);
+  const isAdmin = await checkAdminAccess(event, model, "read");
+  if (!isAdmin) {
+    const resourceConfig = resources?.[model];
+    const isPublic = resourceConfig?.public === true || Array.isArray(resourceConfig?.public) && resourceConfig.public.includes("read");
+    if (!isPublic) {
+      throw createError({
+        statusCode: 401,
+        message: "Unauthorized"
+      });
+    }
+  }
   const table = getTableForModel(model);
-  const singularName = getModelSingularName(model);
   const record = await useDrizzle().select().from(table).where(eq(table.id, Number(id))).get();
   if (!record) {
     throw createError({
       statusCode: 404,
-      message: `${singularName} not found`
+      message: "Record not found"
     });
   }
-  return record;
+  if (isAdmin) {
+    return filterHiddenFields(model, record);
+  } else {
+    return filterPublicColumns(model, record);
+  }
 });

package/dist/runtime/server/api/[model]/[id].patch.d.ts

@@ -1,2 +1,2 @@
-declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<any>>;
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<Record<string, unknown>>>;
 export default _default;

package/dist/runtime/server/api/[model]/[id].patch.js

@@ -1,12 +1,36 @@
-import { eventHandler, getRouterParams, readBody } from "h3";
+import { eventHandler, getRouterParams, readBody, createError } from "h3";
 import { eq } from "drizzle-orm";
-import { getTableForModel, filterUpdatableFields } from "../../utils/modelMapper.js";
+import { getTableForModel, filterUpdatableFields, filterHiddenFields, filterPublicColumns } from "../../utils/modelMapper.js";
 import { useDrizzle } from "#site/drizzle";
+import { useAutoCrudConfig } from "../../utils/config.js";
+import { checkAdminAccess } from "../../utils/auth.js";
 export default eventHandler(async (event) => {
+  const { resources } = useAutoCrudConfig();
   const { model, id } = getRouterParams(event);
+  const isAdmin = await checkAdminAccess(event, model, "update");
+  if (!isAdmin) {
+    const resourceConfig = resources?.[model];
+    const isPublic = resourceConfig?.public === true || Array.isArray(resourceConfig?.public) && resourceConfig.public.includes("update");
+    if (!isPublic) {
+      throw createError({
+        statusCode: 401,
+        message: "Unauthorized"
+      });
+    }
+  }
   const table = getTableForModel(model);
   const body = await readBody(event);
-  const updateData = filterUpdatableFields(model, body);
-  const record = await useDrizzle().update(table).set(updateData).where(eq(table.id, Number(id))).returning().get();
-  return record;
+  const payload = filterUpdatableFields(model, body);
+  const updatedRecord = await useDrizzle().update(table).set(payload).where(eq(table.id, Number(id))).returning().get();
+  if (!updatedRecord) {
+    throw createError({
+      statusCode: 404,
+      message: "Record not found"
+    });
+  }
+  if (isAdmin) {
+    return filterHiddenFields(model, updatedRecord);
+  } else {
+    return filterPublicColumns(model, updatedRecord);
+  }
 });

package/dist/runtime/server/api/[model]/index.get.js

@@ -1,9 +1,30 @@
-import { eventHandler, getRouterParams } from "h3";
-import { getTableForModel } from "../../utils/modelMapper.js";
+import { eventHandler, getRouterParams, createError } from "h3";
+import { getTableForModel, filterHiddenFields, filterPublicColumns } from "../../utils/modelMapper.js";
 import { useDrizzle } from "#site/drizzle";
+import { useAutoCrudConfig } from "../../utils/config.js";
+import { checkAdminAccess } from "../../utils/auth.js";
 export default eventHandler(async (event) => {
+  console.log("[GET] Request received", event.path);
+  const { resources } = useAutoCrudConfig();
   const { model } = getRouterParams(event);
+  const isAdmin = await checkAdminAccess(event, model, "list");
+  if (!isAdmin) {
+    const resourceConfig = resources?.[model];
+    const isPublic = resourceConfig?.public === true || Array.isArray(resourceConfig?.public) && resourceConfig.public.includes("list");
+    if (!isPublic) {
+      throw createError({
+        statusCode: 401,
+        message: "Unauthorized"
+      });
+    }
+  }
   const table = getTableForModel(model);
-  const records = await useDrizzle().select().from(table).all();
-  return records;
+  const results = await useDrizzle().select().from(table).all();
+  return results.map((item) => {
+    if (isAdmin) {
+      return filterHiddenFields(model, item);
+    } else {
+      return filterPublicColumns(model, item);
+    }
+  });
 });

package/dist/runtime/server/api/[model]/index.post.d.ts

@@ -1,2 +1,2 @@
-declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<any>>;
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<Record<string, unknown>>>;
 export default _default;

package/dist/runtime/server/api/[model]/index.post.js

@@ -1,14 +1,29 @@
-import { eventHandler, getRouterParams, readBody } from "h3";
-import { getTableForModel } from "../../utils/modelMapper.js";
+import { eventHandler, getRouterParams, readBody, createError } from "h3";
+import { getTableForModel, filterHiddenFields, filterUpdatableFields, filterPublicColumns } from "../../utils/modelMapper.js";
 import { useDrizzle } from "#site/drizzle";
+import { useAutoCrudConfig } from "../../utils/config.js";
+import { checkAdminAccess } from "../../utils/auth.js";
 export default eventHandler(async (event) => {
+  const { resources } = useAutoCrudConfig();
   const { model } = getRouterParams(event);
+  const isAdmin = await checkAdminAccess(event, model, "create");
+  if (!isAdmin) {
+    const resourceConfig = resources?.[model];
+    const isPublic = resourceConfig?.public === true || Array.isArray(resourceConfig?.public) && resourceConfig.public.includes("create");
+    if (!isPublic) {
+      throw createError({
+        statusCode: 401,
+        message: "Unauthorized"
+      });
+    }
+  }
   const table = getTableForModel(model);
   const body = await readBody(event);
-  const values = {
-    ...body,
-    createdAt: /* @__PURE__ */ new Date()
-  };
-  const record = await useDrizzle().insert(table).values(values).returning().get();
-  return record;
+  const payload = filterUpdatableFields(model, body);
+  const newRecord = await useDrizzle().insert(table).values(payload).returning().get();
+  if (isAdmin) {
+    return filterHiddenFields(model, newRecord);
+  } else {
+    return filterPublicColumns(model, newRecord);
+  }
 });

package/dist/runtime/server/utils/auth.d.ts

@@ -0,0 +1,2 @@
+import type { H3Event } from 'h3';
+export declare function checkAdminAccess(event: H3Event, model: string, action: string): Promise<boolean>;

package/dist/runtime/server/utils/auth.js

@@ -0,0 +1,39 @@
+import { createError } from "h3";
+import { useAutoCrudConfig } from "./config.js";
+import { verifyJwtToken } from "./jwt.js";
+export async function checkAdminAccess(event, model, action) {
+  const { auth } = useAutoCrudConfig();
+  if (!auth?.authentication) {
+    return true;
+  }
+  if (auth.type === "jwt") {
+    if (!auth.jwtSecret) {
+      console.warn("JWT Secret is not configured but auth type is jwt");
+      return false;
+    }
+    return verifyJwtToken(event, auth.jwtSecret);
+  }
+  if (typeof requireUserSession !== "function") {
+    throw new TypeError("requireUserSession is not available");
+  }
+  try {
+    await requireUserSession(event);
+    if (auth.authorization) {
+      if (event.context.ability) {
+        const can = event.context.ability.can(action, model);
+        if (!can) {
+          throw createError({
+            statusCode: 403,
+            message: "Forbidden"
+          });
+        }
+      }
+    }
+    return true;
+  } catch (e) {
+    if (e.statusCode === 403) {
+      throw e;
+    }
+    return false;
+  }
+}

package/dist/runtime/server/utils/config.d.ts

@@ -0,0 +1,2 @@
+import type { RuntimeModuleOptions } from '../../../types.js';
+export declare const useAutoCrudConfig: () => RuntimeModuleOptions;

package/dist/runtime/server/utils/config.js

@@ -0,0 +1,4 @@
+import { useRuntimeConfig } from "#imports";
+export const useAutoCrudConfig = () => {
+  return useRuntimeConfig().autoCrud;
+};

package/dist/runtime/server/utils/jwt.d.ts

@@ -0,0 +1,2 @@
+import type { H3Event } from 'h3';
+export declare function verifyJwtToken(event: H3Event, secret: string): Promise<boolean>;