Address code review feedback - improve validation and documentation

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

content/docs/references/system/AuditConfig.mdx

@@ -7,7 +7,7 @@ description: AuditConfig Schema Reference
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **name** | `string` | ✅ | Configuration name (snake_case) |
+| **name** | `string` | ✅ | Configuration name (snake_case, max 64 chars) |
 | **label** | `string` | ✅ | Display label |
 | **enabled** | `boolean` | optional | Enable audit logging |
 | **eventTypes** | `Enum<'data.create' \| 'data.read' \| 'data.update' \| 'data.delete' \| 'data.export' \| 'data.import' \| 'data.bulk_update' \| 'data.bulk_delete' \| 'auth.login' \| 'auth.login_failed' \| 'auth.logout' \| 'auth.session_created' \| 'auth.session_expired' \| 'auth.password_reset' \| 'auth.password_changed' \| 'auth.email_verified' \| 'auth.mfa_enabled' \| 'auth.mfa_disabled' \| 'auth.account_locked' \| 'auth.account_unlocked' \| 'authz.permission_granted' \| 'authz.permission_revoked' \| 'authz.role_assigned' \| 'authz.role_removed' \| 'authz.role_created' \| 'authz.role_updated' \| 'authz.role_deleted' \| 'authz.policy_created' \| 'authz.policy_updated' \| 'authz.policy_deleted' \| 'system.config_changed' \| 'system.plugin_installed' \| 'system.plugin_uninstalled' \| 'system.backup_created' \| 'system.backup_restored' \| 'system.integration_added' \| 'system.integration_removed' \| 'security.access_denied' \| 'security.suspicious_activity' \| 'security.data_breach' \| 'security.api_key_created' \| 'security.api_key_revoked'>[]` | optional | Event types to audit |
@@ -21,5 +21,5 @@ description: AuditConfig Schema Reference
 | **logReads** | `boolean` | optional | Log read operations |
 | **readSamplingRate** | `number` | optional | Read sampling rate |
 | **logSystemEvents** | `boolean` | optional | Log system events |
-| **customHandlers** | `object[]` | optional | Custom event handlers |
+| **customHandlers** | `object[]` | optional | Custom event handler references |
 | **compliance** | `object` | optional | Compliance configuration |

packages/spec/json-schema/AuditConfig.json

@@ -7,7 +7,8 @@
         "name": {
           "type": "string",
           "pattern": "^[a-z_][a-z0-9_]*$",
-          "description": "Configuration name (snake_case)"
+          "maxLength": 64,
+          "description": "Configuration name (snake_case, max 64 chars)"
         },
         "label": {
           "type": "string",
@@ -195,7 +196,7 @@
           "properties": {
             "retentionDays": {
               "type": "integer",
-              "exclusiveMinimum": 0,
+              "minimum": 1,
               "default": 180,
               "description": "Retention period in days"
             },
@@ -523,14 +524,19 @@
                   "security.api_key_revoked"
                 ],
                 "description": "Event type to handle"
+              },
+              "handlerId": {
+                "type": "string",
+                "description": "Unique identifier for the handler"
               }
             },
             "required": [
-              "eventType"
+              "eventType",
+              "handlerId"
             ],
             "additionalProperties": false
           },
-          "description": "Custom event handlers"
+          "description": "Custom event handler references"
         },
         "compliance": {
           "type": "object",

packages/spec/json-schema/AuditRetentionPolicy.json

@@ -6,7 +6,7 @@
       "properties": {
         "retentionDays": {
           "type": "integer",
-          "exclusiveMinimum": 0,
+          "minimum": 1,
           "default": 180,
           "description": "Retention period in days"
         },

packages/spec/src/system/audit.zod.ts

@@ -271,7 +271,7 @@ export const AuditRetentionPolicySchema = z.object({
    * Retention period in days
    * Default: 180 days (GDPR 6-month requirement)
    */
-  retentionDays: z.number().int().positive().default(180).describe('Retention period in days'),
+  retentionDays: z.number().int().min(1).default(180).describe('Retention period in days'),
 
   /**
    * Whether to archive logs after retention period
@@ -510,10 +510,13 @@ export type AuditEventFilter = z.infer<typeof AuditEventFilterSchema>;
 export const AuditConfigSchema = z.object({
   /**
    * Unique identifier for this audit configuration
+   * Must be in snake_case following ObjectStack conventions
+   * Maximum length: 64 characters
    */
   name: z.string()
     .regex(/^[a-z_][a-z0-9_]*$/)
-    .describe('Configuration name (snake_case)'),
+    .max(64)
+    .describe('Configuration name (snake_case, max 64 chars)'),
 
   /**
    * Human-readable label
@@ -595,14 +598,12 @@ export const AuditConfigSchema = z.object({
 
   /**
    * Custom audit event handlers
+   * Note: Function handlers are for runtime configuration only and will not be serialized to JSON Schema
    */
   customHandlers: z.array(z.object({
     eventType: AuditEventType.describe('Event type to handle'),
-    handler: z.function()
-      .args(AuditEventSchema)
-      .returns(z.promise(z.void()))
-      .describe('Handler function'),
-  })).optional().describe('Custom event handlers'),
+    handlerId: z.string().describe('Unique identifier for the handler'),
+  })).optional().describe('Custom event handler references'),
 
   /**
    * Compliance mode configuration

packages/spec/src/system/tenant.zod.ts

@@ -125,10 +125,11 @@ export type Tenant = z.infer<typeof TenantSchema>;
  * 
  * EXAMPLE RLS POLICY (PostgreSQL):
  * ```sql
- * CREATE POLICY tenant_isolation ON customers
+ * -- Example: Apply RLS policy to a table (e.g., "app_data")
+ * CREATE POLICY tenant_isolation ON app_data
  *   USING (tenant_id = current_setting('app.current_tenant')::text);
  * 
- * ALTER TABLE customers ENABLE ROW LEVEL SECURITY;
+ * ALTER TABLE app_data ENABLE ROW LEVEL SECURITY;
  * ```
  */
 export const RowLevelIsolationStrategySchema = z.object({
@@ -240,7 +241,8 @@ export const SchemaLevelIsolationStrategySchema = z.object({
   schema: z.object({
     /**
      * Schema naming pattern
-     * Use {tenant_id} as placeholder
+     * Use {tenant_id} as placeholder (must contain only alphanumeric and underscores)
+     * The tenant_id will be sanitized before substitution to prevent SQL injection
      */
     namingPattern: z.string().default('tenant_{tenant_id}').describe('Schema naming pattern'),
 
@@ -359,7 +361,8 @@ export const DatabaseLevelIsolationStrategySchema = z.object({
   database: z.object({
     /**
      * Database naming pattern
-     * Use {tenant_id} as placeholder
+     * Use {tenant_id} as placeholder (must contain only alphanumeric and underscores)
+     * The tenant_id will be sanitized before substitution to prevent SQL injection
      */
     namingPattern: z.string().default('tenant_{tenant_id}').describe('Database naming pattern'),