json-rest-api 1.0.24 → 1.0.25

package/README.md

@@ -9,7 +9,8 @@ A powerful REST API plugin for [hooked-api](https://github.com/mobily-enterprise
 * **JSON:API Compliant** - Full support for the JSON:API specification
 * **Relationship Support** - `belongsTo`, `hasMany`, and many-to-many relationships, including polymorphic
 * **Advanced Querying** - Filtering, sorting, pagination, and field selection (sparse fieldsets)
-* **File Uploads** - Built-in support for file handling with multiple storage adapters (local, S3)
+* **Server-Side Row Policies** - Apply mandatory visibility rules before pagination, counts, and relationship loading
+* **File Uploads** - Built-in support for file handling with local storage and a mock S3-style demo adapter
 * **Framework Agnostic** - Works with raw Node.js HTTP, Express, and other Node.js frameworks via flexible connectors
 * **Validation** - Schema-based validation with detailed error messages and custom rules
 * **Simplified Mode** - A developer-friendly option to work with plain JavaScript objects instead of verbose JSON:API structure

package/docs/API.md

@@ -427,7 +427,7 @@ const result = await api.resources.[resourceType].post(params, context)
   },
   simplified: Boolean,      // Override simplified mode (default: true for API)
   transaction: Object,      // Database transaction object
-  returnFullRecord: String  // Override return setting ('no', 'minimal', 'full')
+  returnFullRecord: String|Boolean  // Override return setting ('no', 'minimal', 'full')
 }
 ```
 
@@ -443,7 +443,7 @@ const result = await api.resources.[resourceType].post(params, context)
 | `queryParams` | Object | No | For includes/fields in response |
 | `simplified` | Boolean | No | Override simplified mode (default: true) |
 | `transaction` | Object | No | Database transaction object |
-| `returnFullRecord` | String | No | Override return setting ('no', 'minimal', 'full') |
+| `returnFullRecord` | String\|Boolean | No | Override return setting (`'no'`, `'minimal'`, `'full'`; legacy `true` = `'full'`, `false` = `'no'`) |
 
 When an explicit resource id is provided, `normalizeId` runs before persistence and before any follow-up record fetch used for the return payload. If the normalized id is empty, the request fails as `REST_API_VALIDATION` on `data.id`.
 
@@ -460,6 +460,8 @@ The return value depends on `returnFullRecord` setting and whether it's an API o
 - `'minimal'`: Returns resource with ID only
 - `'full'`: Returns complete resource with all fields
 
+Boolean values are accepted for backward compatibility: `true` is normalized to `'full'` and `false` is normalized to `'no'`. New code should use the string values.
+
 #### HTTP Equivalent
 
 ```http
@@ -611,7 +613,7 @@ const result = await api.resources.[resourceType].put(params, context)
   },
   simplified: Boolean,      // Override simplified mode (default: true for API)
   transaction: Object,      // Database transaction object
-  returnFullRecord: String  // Override return setting ('no', 'minimal', 'full')
+  returnFullRecord: String|Boolean  // Override return setting ('no', 'minimal', 'full')
 }
 ```
 
@@ -626,7 +628,7 @@ const result = await api.resources.[resourceType].put(params, context)
 | `queryParams` | Object | No | For response formatting |
 | `simplified` | Boolean | No | Override simplified mode (default: true) |
 | `transaction` | Object | No | Database transaction object |
-| `returnFullRecord` | String | No | Override return setting |
+| `returnFullRecord` | String\|Boolean | No | Override return setting (`'no'`, `'minimal'`, `'full'`; legacy `true` = `'full'`, `false` = `'no'`) |
 
 `inputRecord.id` and `inputRecord.data.id` always refer to the logical resource id. `idProperty` and storage mapping affect the backing column name, not the API field name, and the resource id is not part of `attributes`.
 
@@ -742,7 +744,7 @@ const result = await api.resources.[resourceType].patch(params, context)
   },
   simplified: Boolean,      // Override simplified mode (default: true for API)
   transaction: Object,      // Database transaction object
-  returnFullRecord: String  // Override return setting ('no', 'minimal', 'full')
+  returnFullRecord: String|Boolean  // Override return setting ('no', 'minimal', 'full')
 }
 ```
 
@@ -757,7 +759,7 @@ const result = await api.resources.[resourceType].patch(params, context)
 | `queryParams` | Object | No | For response formatting |
 | `simplified` | Boolean | No | Override simplified mode (default: true) |
 | `transaction` | Object | No | Database transaction object |
-| `returnFullRecord` | String | No | Override return setting |
+| `returnFullRecord` | String\|Boolean | No | Override return setting (`'no'`, `'minimal'`, `'full'`; legacy `true` = `'full'`, `false` = `'no'`) |
 
 If both the URL id and body id are present, both are normalized before the equality check. If either id normalizes to an empty value, the operation fails before storage is touched.
 
@@ -1315,7 +1317,7 @@ Each API method has its own specific hook execution order. Here's the exact sequ
 ```
 1. beforeData
 2. beforeDataQuery
-3. knexQueryFiltering (multiple times for different filter types)
+3. knexQueryFiltering (multiple handlers for built-in filters and optional server-side policies)
    - polymorphicFiltersHook
    - crossTableFiltersHook
    - basicFiltersHook
@@ -1450,7 +1452,7 @@ Each API method has its own specific hook execution order. Here's the exact sequ
 1. **Processing Hooks**: Only POST, PUT, and PATCH have `beforeProcessing` hooks
 2. **Schema Validation**: Only POST, PUT, and PATCH have schema validation hooks
 3. **Permission Hooks**: GET uses `checkDataPermissions`, while relationship methods use `checkPermissions`
-4. **Query Filtering**: Only QUERY method triggers `knexQueryFiltering` hooks
+4. **Query Filtering**: Collection queries and storage-backed scoped lookups trigger `knexQueryFiltering`; use `RowPolicyPlugin` for mandatory visibility rather than relying on method-specific hook assumptions
 5. **Enrichment**: Only GET and QUERY have `enrichRecord` hooks
 6. **Relationships**: Only GET has `enrichRecordWithRelationships`
 7. **Transactions**: All write methods (POST, PUT, PATCH, DELETE) can trigger `afterCommit`/`afterRollback`
@@ -2292,7 +2294,8 @@ api.addResource({
     
     // No built-in permissions option exists here.
     // Use permission hooks for access decisions, and optional plugins
-    // such as AutoFilterPlugin for dataset scoping.
+    // such as AutoFilterPlugin for equality-based dataset scoping or
+    // RowPolicyPlugin for mandatory SQL visibility predicates.
     
     // Soft delete configuration
     softDelete: {

package/docs/GUIDE/GUIDE_1_Initial_Setup.md

@@ -242,7 +242,7 @@ console.log('Refetched Country:', inspect(countryUsRefetched));
 // }
 ```
 
-(Note that the full JSON:API record includes links to resources, which are automatically generated based on the request headers.)
+(Note that the full JSON:API record includes links to resources, which are generated from explicit URL configuration such as the connector `mountPath` or `publicBaseUrl`.)
 
 As you can see, when `simplified: false` is used:
 
@@ -340,11 +340,13 @@ There are TWO separate settings for this:
 
 This separation allows you to have different behaviors for internal API usage versus external HTTP clients. For example, your internal code might want full records for convenience, while HTTP clients might prefer minimal responses for performance.
 
-Both settings accept three string values:
+Both settings prefer three string values:
 - **`'full'`**: Returns the complete record with all attributes, relationships, computed fields, and links
 - **`'minimal'`**: Returns only the resource type and ID
 - **`'no'`**: Returns nothing (undefined in programmatic calls, 204 No Content in HTTP)
 
+Boolean values are accepted for backward compatibility: `true` is normalized to `'full'` and `false` is normalized to `'no'`. New code should use the string values.
+
 Here's how these settings work:
 
 ```javascript
@@ -796,6 +798,7 @@ Here is a full list of parameters and their respective variables:
 - `returnRecordApi` and `returnRecordTransport` can be either:
   - A string: `'no'`, `'minimal'`, or `'full'` (applies to all methods)
   - An object: `{ post: 'full', put: 'minimal', patch: 'no' }` (per-method configuration)
+  - Legacy booleans: `true` is treated as `'full'`, `false` as `'no'`
 - All parameters support the cascade: per-call → resource-level → plugin-level default
 
 # Logical IDs and Physical Columns

package/docs/GUIDE/GUIDE_2_1_The_Starting_Point.md

@@ -23,9 +23,9 @@ const knex = knexLib({
 const api = new Api({ name: 'book-catalog-api' });
 
 // Install plugins
-await api.use(RestApiPlugin); // URLs auto-detected from request headers
+await api.use(RestApiPlugin);
 await api.use(RestApiKnexPlugin, { knex });
-await api.use(ExpressPlugin, {  mountPath: '/api' }); // Added: Express Plugin
+await api.use(ExpressPlugin, { mountPath: '/api' }); // Links are generated under /api
 
 /// *** ...programmatic calls here... ***
 
@@ -85,4 +85,4 @@ This design provides the best of both worlds: backend developers get full databa
 
 ---
 
-[Back to Guide](./README.md) | [Next: 2.2 Manipulating and searching tables with no relationships](./GUIDE_2_2_Manipulating_And_Searching_Tables.md)
+[Back to Guide](./README.md) | [Next: 2.2 Manipulating and searching tables with no relationships](./GUIDE_2_2_Manipulating_And_Searching_Tables.md)

package/docs/GUIDE/GUIDE_3_Field_Transformations.md

@@ -132,6 +132,8 @@ await api.addResource('users', {
 });
 ```
 
+If a setter throws or rejects, the write fails with a validation error and the transaction rolls back instead of storing the untransformed value.
+
 ### Getters - Transform After Retrieval
 
 ```javascript

package/docs/GUIDE/GUIDE_7_Hooks_Data_Management_And_Plugins.md

@@ -1186,7 +1186,7 @@ api.addScope('articles', {}, {
 
 ### knexQueryFiltering
 
-The `knexQueryFiltering` hook is called during QUERY operations to apply filter conditions. This is a special hook that allows complex query modifications.
+The `knexQueryFiltering` hook is called while storage-backed resource selections are being built. Collection queries run it before sorting and pagination; scoped lookup and relationship paths can also run it. This is a special hook that allows complex query modifications. Use the supported [Row Policies](GUIDE_X_Row_Policies.md) contract for mandatory resource visibility.
 
 **When**: During `dataQuery` execution, before sorting and pagination  
 **Purpose**: Apply filters, add JOINs, modify query conditions

package/docs/GUIDE/GUIDE_X_Autofiltering.md

@@ -77,6 +77,69 @@ await api.use(AutoFilterPlugin, {
 })
 ```
 
+## Storage Backends
+
+`AutoFilterPlugin` works with either database storage plugin:
+
+- `RestApiKnexPlugin` for resources backed by normal database tables
+- `RestApiAnyapiKnexPlugin` for logical resources backed by AnyAPI canonical storage
+
+An `Api` instance has one storage engine. Install either storage plugin, then install `AutoFilterPlugin`. If an application keeps core resources in normal tables and user-defined resources in AnyAPI, create one `Api` instance for each storage engine. Each instance owns its resources and autofilter configuration.
+
+Autofilter definitions always use logical schema field names. The selected storage plugin translates those fields to normal table columns or AnyAPI canonical slots.
+
+### Workspace Scoping with AnyAPI
+
+AnyAPI's `tenantId` is fixed when `RestApiAnyapiKnexPlugin` is installed. It identifies the metadata and canonical-storage namespace; it is not a per-request workspace value. For one AnyAPI instance serving multiple application workspaces, use a stable internal `tenantId` and persist `workspace_id` on every workspace-scoped resource:
+
+```js
+import { Api } from 'hooked-api'
+import {
+  RestApiPlugin,
+  RestApiAnyapiKnexPlugin,
+  AutoFilterPlugin
+} from 'json-rest-api'
+
+const api = new Api({ name: 'form-data-api' })
+
+await api.use(RestApiPlugin)
+await api.use(RestApiAnyapiKnexPlugin, {
+  knex,
+  tenantId: 'application'
+})
+
+await api.use(AutoFilterPlugin, {
+  resolvers: {
+    workspace: ({ context }) => context.session?.workspaceId
+  },
+  presets: {
+    workspace: {
+      filters: [
+        { field: 'workspace_id', resolver: 'workspace' }
+      ]
+    }
+  }
+})
+
+await api.addResource('form_123', {
+  schema: {
+    id: { type: 'id' },
+    workspace_id: { type: 'string', required: true },
+    customer_name: { type: 'string', required: true },
+    subscribed: { type: 'boolean' }
+  },
+  autofilter: 'workspace'
+})
+```
+
+In this arrangement:
+
+- `tenantId: 'application'` selects one fixed AnyAPI metadata and canonical-storage namespace. Do not derive it from request context.
+- `workspace_id` isolates application workspaces. `AutoFilterPlugin` stamps it on writes and filters by it on reads.
+- A trusted resolver supplies the current workspace. Do not resolve it directly from an unverified request field.
+- User-defined forms with different schemas need distinct resource names within the AnyAPI namespace, such as `form_123` and `form_456`. Put the workspace autofilter on each resource.
+- Workspaces may use the same logical resource when they share its schema; `workspace_id` still keeps their records separate.
+
 ## Resource Configuration
 
 Apply a preset by name:

package/docs/GUIDE/GUIDE_X_File_Uploads.md

@@ -19,7 +19,7 @@ The file handling system consists of three main components:
 
 1. **FileHandlingPlugin** - Orchestrates file detection and processing
 2. **Protocol Detectors** - Parse files from different protocols (HTTP, Express)
-3. **Storage Adapters** - Save files to different backends (local, S3, etc.)
+3. **Storage Adapters** - Save files to local storage or generate mock S3-style URLs for demos
 
 ### How It Works
 
@@ -115,11 +115,11 @@ Storage adapters handle where and how files are saved. The library includes two
 | **Extension Whitelist** | ✅ Yes | ❌ No |
 | **Duplicate Handling** | ✅ Yes | ✅ Automatic |
 | **Custom Naming** | ✅ Yes | ❌ No |
-| **Best For** | Local file storage | Cloud storage |
+| **Best For** | Local file storage | Tests, examples, S3-style URL demos |
 
-### S3Storage
+### S3Storage (Mock/Demo)
 
-Saves files to Amazon S3 or S3-compatible storage:
+Generates S3-style URLs without uploading files to Amazon S3:
 
 ```javascript
 import { S3Storage } from 'json-rest-api/plugins/storage/s3-storage.js';
@@ -129,7 +129,7 @@ const s3Storage = new S3Storage({
   region: 'us-east-1',                 // AWS region (default: 'us-east-1')
   prefix: 'uploads/',                  // Path prefix in bucket (default: '')
   acl: 'public-read',                  // Access control (default: 'public-read')
-  mockMode: false                      // Use mock mode? (default: true)
+  mockMode: true                       // Only supported mode
 });
 ```
 
@@ -137,7 +137,7 @@ const s3Storage = new S3Storage({
 - Always generates random hash + extension (e.g., `uploads/a7f8d9e2b4c6e1f3.jpg`)
 - Original filenames are never used for security
 
-**Note**: The included S3Storage is a mock implementation for demonstration. For production use, you'll need to implement the actual AWS SDK calls.
+**Note**: The included S3Storage is a mock implementation for demonstration. `mockMode: false` throws a clear error because real S3 uploads are not implemented. For production use, provide your own storage adapter or add an AWS SDK-backed implementation.
 
 ### LocalStorage
 
@@ -187,9 +187,11 @@ const localStorage = new LocalStorage({
    }
    // Result: "user_12345_1672531200000.jpg"
    ```
+   Custom generators must return a basename only, not a path. Values containing `/`, `\`, drive prefixes, or only whitespace are rejected.
 
 **Security Features:**
-- Path traversal protection (removes `..` and `/`)
+- Path traversal protection (sanitizes original names and rejects path-like custom names)
+- Custom generated names are restricted to basenames
 - Control character filtering
 - Extension validation against whitelist
 - Automatic duplicate handling
@@ -218,12 +220,15 @@ class MyCustomStorage {
   }
   
   async delete(url) {
-    // Optional: implement file deletion
+    // Optional but recommended: FileHandlingPlugin calls this after
+    // an uploaded file's write transaction rolls back.
     await deleteFileSomewhere(url);
   }
 }
 ```
 
+`FileHandlingPlugin` always calls detector-provided `file.cleanup()` after parsing, including validation failures. If a file has already been uploaded and the later resource write rolls back, the plugin calls `storage.delete(url)` when the adapter implements it. Storage adapters that need rollback cleanup should make `delete(url)` idempotent for URLs returned by `upload(file)`.
+
 ## Protocol Configuration
 
 Different protocols have different configuration options for file parsing.
@@ -536,11 +541,11 @@ const organizedStorage = new LocalStorage({
   nameStrategy: 'custom',
   nameGenerator: async (file) => {
     const date = new Date();
-    const dateDir = `${date.getFullYear()}/${String(date.getMonth() + 1).padStart(2, '0')}`;
-    return `${dateDir}/${crypto.randomBytes(16).toString('hex')}`;
+    const datePrefix = `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}`;
+    return `${datePrefix}-${crypto.randomBytes(16).toString('hex')}`;
   }
 });
-// Saves as: "2024/01/a7f8d9e2b4c6e1f3.jpg"
+// Saves as: "2024-01-a7f8d9e2b4c6e1f3.jpg"
 ```
 
 ### Using cURL
@@ -721,4 +726,4 @@ Then visit http://localhost:3000 to see the test forms.
 - Add image processing (thumbnails, resizing)
 - Implement virus scanning for uploads
 - Add progress tracking for large files
-- Create a chunked upload system for very large files
+- Create a chunked upload system for very large files