Address code review feedback: Enhanced security docs and type safety

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

Author: Copilot

packages/spec/src/auth/scim.zod.ts

@@ -404,17 +404,41 @@ export const SCIMEnterpriseUserSchema = z.object({
 
 export type SCIMEnterpriseUser = z.infer<typeof SCIMEnterpriseUserSchema>;
 
+/**
+ * SCIM Schema URI Validator
+ * Validates that schema URIs are known SCIM schema identifiers
+ */
+const SCIMSchemaURISchema = z.enum([
+  SCIM_SCHEMAS.USER,
+  SCIM_SCHEMAS.GROUP,
+  SCIM_SCHEMAS.ENTERPRISE_USER,
+  SCIM_SCHEMAS.RESOURCE_TYPE,
+  SCIM_SCHEMAS.SERVICE_PROVIDER_CONFIG,
+  SCIM_SCHEMAS.SCHEMA,
+  SCIM_SCHEMAS.LIST_RESPONSE,
+  SCIM_SCHEMAS.PATCH_OP,
+  SCIM_SCHEMAS.BULK_REQUEST,
+  SCIM_SCHEMAS.BULK_RESPONSE,
+  SCIM_SCHEMAS.ERROR,
+]);
+
 /**
  * SCIM User Schema (Core)
  * Complete SCIM 2.0 User resource
  */
 export const SCIMUserSchema = z.object({
   /**
    * SCIM schema URIs
+   * Must include at minimum the core User schema URI
    */
   schemas: z.array(z.string())
+    .min(1)
+    .refine(
+      (schemas) => schemas.includes(SCIM_SCHEMAS.USER),
+      'Must include core User schema URI'
+    )
     .default([SCIM_SCHEMAS.USER])
-    .describe('SCIM schema URIs'),
+    .describe('SCIM schema URIs (must include User schema)'),
 
   /**
    * Unique identifier
@@ -661,10 +685,16 @@ export type SCIMMemberReference = z.infer<typeof SCIMMemberReferenceSchema>;
 export const SCIMGroupSchema = z.object({
   /**
    * SCIM schema URIs
+   * Must include at minimum the core Group schema URI
    */
   schemas: z.array(z.string())
+    .min(1)
+    .refine(
+      (schemas) => schemas.includes(SCIM_SCHEMAS.GROUP),
+      'Must include core Group schema URI'
+    )
     .default([SCIM_SCHEMAS.GROUP])
-    .describe('SCIM schema URIs'),
+    .describe('SCIM schema URIs (must include Group schema)'),
 
   /**
    * Unique identifier
@@ -704,9 +734,18 @@ export const SCIMGroupSchema = z.object({
 
 export type SCIMGroup = z.infer<typeof SCIMGroupSchema>;
 
+/**
+ * SCIM Resource Union Type
+ * Known SCIM resource types for type-safe list responses
+ */
+export type SCIMResource = SCIMUser | SCIMGroup;
+
 /**
  * SCIM List Response
  * Paginated list of resources
+ * 
+ * Generic type T allows for type-safe responses when the resource type is known.
+ * For mixed resource types, use SCIMResource union.
  */
 export const SCIMListResponseSchema = z.object({
   /**
@@ -726,9 +765,10 @@ export const SCIMListResponseSchema = z.object({
 
   /**
    * Resources returned in this response
+   * Use SCIMListResponseOf<T> for type-safe responses
    */
-  Resources: z.array(z.any())
-    .describe('Resources array'),
+  Resources: z.array(z.union([SCIMUserSchema, SCIMGroupSchema, z.record(z.any())]))
+    .describe('Resources array (Users, Groups, or custom resources)'),
 
   /**
    * 1-based index of the first result
@@ -890,10 +930,16 @@ export const SCIM = {
   /**
    * Create an error response
    */
-  error: (status: number, detail: string, scimType?: string): SCIMError => ({
+  error: (
+    status: number,
+    detail: string,
+    scimType?: 'invalidFilter' | 'tooMany' | 'uniqueness' | 'mutability' | 
+                'invalidSyntax' | 'invalidPath' | 'noTarget' | 'invalidValue' | 
+                'invalidVers' | 'sensitive'
+  ): SCIMError => ({
     schemas: [SCIM_SCHEMAS.ERROR],
     status,
     detail,
-    scimType: scimType as any,
+    scimType,
   }),
 } as const;

packages/spec/src/permission/rls.zod.ts

@@ -261,49 +261,68 @@ export const RowLevelSecurityPolicySchema = z.object({
    * This is a SQL-like expression evaluated for each row.
    * Only rows where this expression returns TRUE are accessible.
    * 
+   * **Security Note**: RLS conditions are executed at the database level with
+   * parameterized queries. The implementation must use prepared statements
+   * to prevent SQL injection. Never concatenate user input directly into
+   * RLS conditions.
+   * 
+   * **SQL Dialect**: Compatible with PostgreSQL SQL syntax. Implementations
+   * may adapt to other databases (MySQL, SQL Server, etc.) but should maintain
+   * semantic equivalence.
+   * 
    * Available context variables:
    * - `current_user.id` - Current user's ID
    * - `current_user.tenant_id` - Current user's tenant
    * - `current_user.role` - Current user's role
    * - `current_user.department` - Current user's department
    * - `current_user.*` - Any custom user field
    * - `NOW()` - Current timestamp
+   * - `CURRENT_DATE` - Current date
+   * - `CURRENT_TIME` - Current time
    * 
    * Supported operators:
-   * - Comparison: =, !=, <, >, <=, >=
+   * - Comparison: =, !=, <, >, <=, >=, <> (not equal)
    * - Logical: AND, OR, NOT
    * - NULL checks: IS NULL, IS NOT NULL
    * - Set operations: IN, NOT IN
-   * - String: LIKE, NOT LIKE
+   * - String: LIKE, NOT LIKE, ILIKE (case-insensitive)
+   * - Pattern matching: ~ (regex), !~ (not regex)
    * - Subqueries: (SELECT ...)
+   * - Array operations: ANY, ALL
+   * 
+   * **Prohibited**: Dynamic SQL, DDL statements, DML statements (INSERT/UPDATE/DELETE)
    * 
    * @example "tenant_id = current_user.tenant_id"
    * @example "owner_id = current_user.id OR created_by = current_user.id"
    * @example "department IN (SELECT department FROM user_departments WHERE user_id = current_user.id)"
    * @example "status = 'active' AND expiry_date > NOW()"
    */
   using: z.string()
-    .describe('Filter condition (SQL WHERE clause syntax)'),
+    .describe('Filter condition (PostgreSQL SQL WHERE clause syntax with parameterized context variables)'),
 
   /**
    * CHECK clause - Validation for INSERT/UPDATE operations.
    * 
    * Similar to USING but applies to new/modified rows.
    * Prevents users from creating/updating rows they wouldn't be able to see.
    * 
-   * If not specified, defaults to the USING clause.
+   * **Default Behavior**: If not specified, implementations should use the
+   * USING clause as the CHECK clause. This ensures data integrity by preventing
+   * users from creating records they cannot view.
    * 
    * Use cases:
    * - Prevent cross-tenant data creation
    * - Enforce mandatory field values
    * - Validate data integrity rules
+   * - Restrict certain operations (e.g., only allow creating "draft" status)
    * 
    * @example "tenant_id = current_user.tenant_id"
    * @example "status IN ('draft', 'pending')" - Only allow certain statuses
+   * @example "created_by = current_user.id" - Must be the creator
    */
   check: z.string()
     .optional()
-    .describe('Validation condition for INSERT/UPDATE (defaults to using clause)'),
+    .describe('Validation condition for INSERT/UPDATE (defaults to USING clause if not specified - enforced at application level)'),
 
   /**
    * Restrict this policy to specific roles.