nuxt-auto-crud 2.3.0 → 2.4.0

package/README.md

@@ -108,9 +108,9 @@ nuxt dev
 
 ---
 
-## 🌐 Exposed Dynamic RESTful CRUD endpoints
+## 🌐 Data APIs (Dynamic RESTful CRUD)
 
-Nb: Endpoints follow the pattern `/api/_nac/:model`.
+> Note: All endpoints follow the pattern ${nacEndpointPrefix}/:model. By default, this is /api/_nac/:model.
 
 | Method | Endpoint | Action |
 | --- | --- | --- |
@@ -133,15 +133,23 @@ Nb: Endpoints follow the pattern `/api/_nac/:model`.
 
 ---
 
-## 🛠 Frontend Integration APIs
+## 🛠 Introspection & Metadata APIs
 
-In addition to CRUD endpoints, **nac** provides metadata APIs to power dynamic forms and tables in your frontend.
+Use these endpoints to build dynamic UI components (like menus and forms) or provide context to AI agents. These use the `_schemas` and `_meta` reserved paths.
 
-* **List Resources**: `GET /api/_nac/_schemas` returns all tables (excluding system-protected tables).
-* **Resource Metadata**: `GET /api/_nac/_schemas/:resource` returns the field definitions, validation rules, and relationship data for a specific table.
-* **Agentic Discovery**: `GET /api/_nac/_meta?format=md` returns a markdown manifest for LLM context injection.
+### 1. Discovery Endpoints
 
----
+* **List Resource Names**: `GET /api/_nac/_schemas`
+* Returns an array of all available table names. Useful for generating dynamic navigation menus.
+* **Resource Metadata**: `GET /api/_nac/_schemas/:resource`
+* Returns field definitions, validation rules, and `isReadOnly` status for a specific table.
+* **Example:** `GET /api/_nac/_schemas/users` returns the schema for the users table.
+
+### 2. Agentic Discovery
+
+* **Manifest**: `GET /api/_nac/_meta?format=md`
+* Returns a token-efficient Markdown manifest for LLM context injection.
+* **Security:** Requires `NUXT_AUTO_CRUD_AGENTIC_TOKEN` (min 16 characters) in your `.env`.
 
 ### Schema Interface
 
@@ -187,8 +195,9 @@ Enabling `authentication` in the `autoCrud` config protects all **nac** routes (
 
 ### 🔒 Access Control & Data Safety
 
-* **`apiHiddenFields`**: Globally hides sensitive columns from all API responses. Default: `['password', 'secret', 'token', 'reset_token', 'reset_expires', 'github_id', 'google_id']`.
-* **`formHiddenFields`**: Columns excluded from the frontend schema metadata to prevent user input. Defaults to `apiHiddenFields` plus system-managed fields like `id`, `uuid`, `createdAt`, `updatedAt`, `createdBy`, etc.
+* **`apiHiddenFields`**: Globally hides sensitive columns from all API responses. Default: ['password', 'secret', 'token', 'resetToken', 'resetExpires', 'githubId', 'googleId'].
+* **`formHiddenFields`**: Columns excluded from the frontend schema metadata to prevent user input. Defaults to apiHiddenFields plus system-managed fields like `id`, `uuid`, `createdAt`, `updatedAt`, `deletedAt`, `createdBy`, and `updatedBy`.
+* **`formReadOnlyFields`**: Columns visible in the UI for context but protected from user modification (e.g., slug, status).
 * **Response Scrubbing**: If a field is in `apiHiddenFields` or does not exist in the schema, it is silently stripped from the response even if listed in `publicResources`.
 
 ---
@@ -198,11 +207,15 @@ Enabling `authentication` in the `autoCrud` config protects all **nac** routes (
 | Key | Default | Description |
 | --- | --- | --- |
 | `statusFiltering` | `false` | Enables/disables automatic filtering of records based on the `status` column. |
-| `realtime` | `false` | Enables/disables real-time capabilities. |
+| `realtime` | `false` | Enables real-time broadcasting of all Create, Update, and Delete (CUD) operations via SSE. |
 | `auth.authentication` | `false` | Requires a valid session for all NAC routes. |
 | `auth.authorization` | `false` | Enables role/owner-based access checks. |
 | `auth.ownerKey` | `'createdBy'` | The column name used to identify the record creator. |
 | `publicResources` | `{}` | Defines tables and specific columns accessible without auth. |
+| `apiHiddenFields` | `NAC_API_HIDDEN_FIELDS` | Arrays of keys to exclude from all API responses. |
+| `formHiddenFields` | `NAC_FORM_HIDDEN_FIELDS` | Arrays of keys to exclude from dynamic forms. |
+| `formReadOnlyFields` | `NAC_FORM_READ_ONLY_FIELDS` | List of visible but non-editable fields (UI only). |
+| `agenticToken` | `''` | Secret key used to secure the /_meta endpoint, preventing unauthorized AI agents from introspecting your schema. |
 | `nacEndpointPrefix` | `'/api/_nac'` | The base path for NAC routes. Access via `useRuntimeConfig().public.autoCrud`. |
 | `schemaPath` | `'server/db/schema'` | Location of your Drizzle schema files. |
 
@@ -221,8 +234,9 @@ autoCrud: {
     users: ['id', 'name', 'email'],
   },
   apiHiddenFields: ['password'], 
-  agenticToken: process.env.NAC_AGENTIC_TOKEN, 
-  formHiddenFields: [], 
+  formHiddenFields: ['createdAt'], // All fields should be camelCase
+  formReadOnlyFields: ['slug', 'externalId'], // Locked for user input
+  agenticToken: '', 
   nacEndpointPrefix: '/api/_nac',
   schemaPath: 'server/db/schema',
 }
@@ -253,7 +267,7 @@ If `list_active` is present, it applies a hybrid OR logic: users can see all act
 // Example: Setting context in your Auth Middleware
 event.context.nac = {
   userId: user.id,
-  resourcePermissions: user.permissions[model], // e.g., ['list_own', 'list']
+  resourcePermissions: user.permissions[model], // e.g., ['list_own', 'list_active']
   record: null, // Optional: Pre-fetched record to prevent double-hitting the DB
 }
 
@@ -306,6 +320,3 @@ useNacAutoCrudSSE(({ table, action, data: sseData, primaryKey }) => {
 ```
 ---
 
-
-
----

package/dist/module.d.mts

@@ -14,13 +14,14 @@ interface ModuleOptions {
     publicResources: Record<string, string[]>; /** Allowed fields for public apis */
     nacEndpointPrefix: string;
     formHiddenFields: string[]; /** UI: Hidden from forms */
+    formReadOnlyFields: string[]; /** UI: Read only fields */
 }
 declare module '@nuxt/schema' {
     interface RuntimeConfig {
-        autoCrud: Omit<ModuleOptions, 'nacEndpointPrefix' | 'formHiddenFields'>;
+        autoCrud: Omit<ModuleOptions, 'nacEndpointPrefix' | 'formHiddenFields' | 'formReadOnlyFields'>;
     }
     interface PublicRuntimeConfig {
-        autoCrud: Pick<ModuleOptions, 'nacEndpointPrefix' | 'formHiddenFields'>;
+        autoCrud: Pick<ModuleOptions, 'nacEndpointPrefix' | 'formHiddenFields' | 'formReadOnlyFields'>;
     }
 }
 

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-auto-crud",
   "configKey": "autoCrud",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "unknown"

package/dist/module.mjs

@@ -1,5 +1,5 @@
 import { defineNuxtModule, createResolver, addImportsDir, addServerImportsDir, addServerHandler } from '@nuxt/kit';
-import { NAC_FORM_HIDDEN_FIELDS, NAC_API_HIDDEN_FIELDS } from '../dist/runtime/server/utils/constants.js';
+import { NAC_FORM_READ_ONLY_FIELDS, NAC_FORM_HIDDEN_FIELDS, NAC_API_HIDDEN_FIELDS } from '../dist/runtime/server/utils/constants.js';
 
 const module$1 = defineNuxtModule({
   meta: {
@@ -21,6 +21,7 @@ const module$1 = defineNuxtModule({
     schemaPath: "server/db/schema",
     // Public config
     formHiddenFields: NAC_FORM_HIDDEN_FIELDS,
+    formReadOnlyFields: NAC_FORM_READ_ONLY_FIELDS,
     nacEndpointPrefix: "/api/_nac"
   },
   async setup(options, nuxt) {
@@ -29,9 +30,9 @@ const module$1 = defineNuxtModule({
     nuxt.options.alias["#nac/shared"] = resolver.resolve("./runtime/shared");
     nuxt.options.alias["#nac/types"] = resolver.resolve("./runtime/server/types");
     nuxt.options.alias["#nac/schema"] = resolver.resolve(nuxt.options.rootDir, options.schemaPath);
-    const { formHiddenFields, nacEndpointPrefix, ...privateOptions } = options;
+    const { formHiddenFields, nacEndpointPrefix, formReadOnlyFields, ...privateOptions } = options;
     nuxt.options.runtimeConfig.autoCrud = privateOptions;
-    nuxt.options.runtimeConfig.public.autoCrud = { formHiddenFields, nacEndpointPrefix };
+    nuxt.options.runtimeConfig.public.autoCrud = { formHiddenFields, nacEndpointPrefix, formReadOnlyFields };
     addImportsDir(resolver.resolve("./runtime/composables"));
     addServerImportsDir(resolver.resolve("./runtime/server/utils"));
     nuxt.hook("prepare:types", ({ references }) => {

package/dist/runtime/server/api/_nac/_meta.get.js

@@ -1,5 +1,5 @@
 import { db } from "@nuxthub/db";
-import { eventHandler, getQuery, getHeader } from "h3";
+import { eventHandler, getQuery, getHeader, setResponseHeader } from "h3";
 import { useRuntimeConfig } from "#imports";
 import { getSchemaDefinition, modelTableMap } from "../../utils/modelMapper.js";
 export default eventHandler(async (event) => {

package/dist/runtime/server/middleware/nac-guard.js

@@ -12,7 +12,7 @@ export default defineEventHandler(async (event) => {
     const isUserAuthenticated = Boolean(event.context.nac?.userId);
     if (isAuthEnabled && !isUserAuthenticated) {
       const model = getModelName(pathname, nacEndpointPrefix);
-      if (model && isPublicResource(model)) {
+      if (model && isPublicResource(model, config.autoCrud.publicResources)) {
         event.context.nac.isPublic = true;
       } else {
         throw new AuthenticationError("Unauthorized").toH3();
@@ -22,18 +22,26 @@ export default defineEventHandler(async (event) => {
   }
   const token = getQuery(event).token;
   const { agenticToken } = config.autoCrud;
-  if (!agenticToken || token !== agenticToken) {
+  if (!validateToken(token, agenticToken)) {
     throw new AuthenticationError("Invalid agentic token").toH3();
   }
 });
+function validateToken(token, agenticToken) {
+  if (!token || !agenticToken || agenticToken.length < 16) return false;
+  if (token.length !== agenticToken.length) return false;
+  let diff = 0;
+  for (let i = 0; i < token.length; i++) {
+    diff |= token.charCodeAt(i) ^ agenticToken.charCodeAt(i);
+  }
+  return diff === 0;
+}
 function getModelName(pathname, nacEndpointPrefix) {
   const regex = new RegExp(`^${nacEndpointPrefix}/([^/]+)`);
   const match = pathname.match(regex);
   return match ? match[1] : null;
 }
-function isPublicResource(model) {
-  const { publicResources } = useRuntimeConfig().autoCrud;
-  return Object.keys(publicResources || {}).includes(model);
+function isPublicResource(model, publicResources = {}) {
+  return Object.keys(publicResources).includes(model);
 }
 function isAgenticPath(pathname) {
   return pathname.includes("/_meta");

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

@@ -5,14 +5,19 @@
 export declare const NAC_API_HIDDEN_FIELDS: string[];
 /**
  * 2. FORM_HIDDEN_FIELDS
- * User should not edit these. System handles these.
- * Includes System Fields (minus status/updated_at) + Hidden Fields.
  */
 export declare const NAC_FORM_HIDDEN_FIELDS: string[];
 /**
- * 3. TABLE_HIDDEN_FIELDS
- * UI clutter reduction for DataTables.
+ * 3. DATA_TABLE_HIDDEN_FIELDS
  */
 export declare const NAC_DATA_TABLE_HIDDEN_FIELDS: string[];
-/** Tables used by the underlying database engine/migration tool */
+/**
+ * 4. FORM_READ_ONLY_FIELDS
+ * Visible in forms for context, but not editable.
+ */
+export declare const NAC_FORM_READ_ONLY_FIELDS: never[];
+/**
+ * Tables used by the engine.
+ * These match the actual DB table names (usually snake_case or specific migration names).
+ */
 export declare const NAC_SYSTEM_TABLES: string[];

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

@@ -1,32 +1,27 @@
-const NAC_SYSTEM_FIELDS = [
-  "id",
-  "uuid",
-  "created_at",
-  "updated_at",
-  "deleted_at",
-  "created_by",
-  "updated_by"
-];
 export const NAC_API_HIDDEN_FIELDS = [
   "password",
   "secret",
   "token",
-  "reset_token",
-  "reset_expires",
-  "github_id",
-  "google_id"
+  "resetToken",
+  "resetExpires",
+  "githubId",
+  "googleId"
 ];
 export const NAC_FORM_HIDDEN_FIELDS = [
-  // ...NAC_API_HIDDEN_FIELDS, // hidden by default.
-  ...NAC_SYSTEM_FIELDS
-  // from the api, hide system fields too
+  ...NAC_API_HIDDEN_FIELDS,
+  "id",
+  "uuid",
+  "createdAt",
+  "updatedAt",
+  "deletedAt",
+  "createdBy",
+  "updatedBy"
 ];
 export const NAC_DATA_TABLE_HIDDEN_FIELDS = [
-  // ...NAC_API_HIDDEN_FIELDS, // hidden by default.
-  "updated_at",
-  "deleted_at",
-  "created_by",
-  "updated_by"
-  // from the api, hide these fields too
+  "updatedAt",
+  "deletedAt",
+  "createdBy",
+  "updatedBy"
 ];
+export const NAC_FORM_READ_ONLY_FIELDS = [];
 export const NAC_SYSTEM_TABLES = ["_hub_migrations", "d1_migrations", "sqlite_sequence"];

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

@@ -76,11 +76,11 @@ export async function getSchemaDefinition(modelName) {
   if (!table) throw new ResourceNotFoundError(modelName);
   const config = useRuntimeConfig();
   const apiHiddenFields = config.autoCrud.apiHiddenFields;
-  const formHiddenFields = config.public.autoCrud.formHiddenFields;
+  const { formHiddenFields, formReadOnlyFields } = config.public.autoCrud;
   const columns = getColumns(table);
   const relations = await resolveTableRelations(table);
   const shape = createInsertSchema(table).shape;
-  const fields = Object.entries(columns).filter(([name]) => !apiHiddenFields.includes(name)).map(([name, col]) => {
+  const fields = Object.entries(columns).filter(([name]) => !apiHiddenFields.includes(name) && !formHiddenFields.includes(name)).map(([name, col]) => {
     const zodField = shape[name];
     const zodTypeName = zodField?._def?.typeName;
     let type = ZOD_TYPE_MAP[zodTypeName] ?? "string";
@@ -105,7 +105,7 @@ export async function getSchemaDefinition(modelName) {
       selectOptions,
       required: colInternal.notNull ?? false,
       references: relations[name],
-      isReadOnly: formHiddenFields.includes(name)
+      isReadOnly: formReadOnlyFields.includes(name) || name === "id"
     };
   });
   return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-auto-crud",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Dynamic RESTful CRUD APIs for Nuxt without code generation, fully schema-driven.",
   "author": "Cliford Pereira",
   "license": "MIT",