Fix code review issues: schema validation, INSERT-only RLS, context mapping docs

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

Author: Copilot

PROTOCOL_OPTIMIZATION_PLAN.md

@@ -664,9 +664,8 @@ export const RowLevelSecuritySchema = z.object({
 
 #### 2. SCIM 2.0 Protocol 👥
 **文件**: 
-- `packages/spec/src/auth/scim.zod.ts`
-- `packages/spec/src/auth/scim-user.zod.ts`
-- `packages/spec/src/auth/scim-group.zod.ts`
+- `packages/spec/src/auth/scim.zod.ts` (包含 User, Group, Enterprise Extension)
+- `packages/spec/src/auth/scim.test.ts`
 
 **测试**: `packages/spec/src/auth/scim.test.ts`
 **文档**: `content/docs/specifications/auth/scim.mdx`
@@ -749,8 +748,7 @@ export const RowLevelSecuritySchema = z.object({
 
 ### P0 - 必须立即实现
 - [ ] `permission/rls.zod.ts` - Row-Level Security
-- [ ] `auth/scim.zod.ts` - SCIM 2.0 User
-- [ ] `auth/scim-group.zod.ts` - SCIM 2.0 Group
+- [ ] `auth/scim.zod.ts` - SCIM 2.0 User & Group
 - [ ] `auth/scim.test.ts` - SCIM Tests
 
 ### P1 - 高优先级 (1个月内)

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

@@ -404,24 +404,6 @@ 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
@@ -638,6 +620,21 @@ export const SCIMUserSchema = z.object({
   [SCIM_SCHEMAS.ENTERPRISE_USER]: SCIMEnterpriseUserSchema
     .optional()
     .describe('Enterprise user attributes'),
+}).superRefine((data, ctx) => {
+  // Validate that enterprise extension schema URI is present when extension data is provided
+  const hasEnterpriseExtension = data[SCIM_SCHEMAS.ENTERPRISE_USER] != null;
+  if (!hasEnterpriseExtension) {
+    return;
+  }
+
+  const schemas = data.schemas || [];
+  if (!schemas.includes(SCIM_SCHEMAS.ENTERPRISE_USER)) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['schemas'],
+      message: `schemas must include "${SCIM_SCHEMAS.ENTERPRISE_USER}" when enterprise user extension attributes are present`,
+    });
+  }
 });
 
 export type SCIMUser = z.infer<typeof SCIMUserSchema>;
@@ -752,6 +749,11 @@ export const SCIMListResponseSchema = z.object({
    * SCIM schema URI
    */
   schemas: z.array(z.string())
+    .min(1)
+    .refine(
+      (schemas) => schemas.includes(SCIM_SCHEMAS.LIST_RESPONSE),
+      { message: `schemas must include ${SCIM_SCHEMAS.LIST_RESPONSE}` }
+    )
     .default([SCIM_SCHEMAS.LIST_RESPONSE])
     .describe('SCIM schema URIs'),
 
@@ -800,6 +802,11 @@ export const SCIMErrorSchema = z.object({
    * SCIM schema URI
    */
   schemas: z.array(z.string())
+    .min(1)
+    .refine(
+      (schemas) => schemas.includes(SCIM_SCHEMAS.ERROR),
+      { message: `schemas must include ${SCIM_SCHEMAS.ERROR}` }
+    )
     .default([SCIM_SCHEMAS.ERROR])
     .describe('SCIM schema URIs'),
 
@@ -876,6 +883,11 @@ export const SCIMPatchRequestSchema = z.object({
    * SCIM schema URI
    */
   schemas: z.array(z.string())
+    .min(1)
+    .refine(
+      (schemas) => schemas.includes(SCIM_SCHEMAS.PATCH_OP),
+      { message: 'SCIM PATCH requests must include the PatchOp schema URI' }
+    )
     .default([SCIM_SCHEMAS.PATCH_OP])
     .describe('SCIM schema URIs'),
 

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

@@ -261,6 +261,9 @@ export const RowLevelSecurityPolicySchema = z.object({
    * This is a SQL-like expression evaluated for each row.
    * Only rows where this expression returns TRUE are accessible.
    * 
+   * **Note**: For INSERT-only policies, USING is not required (only CHECK is needed).
+   * For SELECT/UPDATE/DELETE operations, USING is required.
+   * 
    * **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
@@ -272,14 +275,18 @@ export const RowLevelSecurityPolicySchema = z.object({
    * 
    * Available context variables:
    * - `current_user.id` - Current user's ID
-   * - `current_user.tenant_id` - Current user's tenant
+   * - `current_user.tenant_id` - Current user's tenant (maps to `tenantId` in RLSUserContext)
    * - `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
    * 
+   * **Context Variable Mapping**: The RLSUserContext schema uses camelCase (e.g., `tenantId`),
+   * but expressions use snake_case with `current_user.` prefix (e.g., `current_user.tenant_id`).
+   * Implementations must handle this mapping.
+   * 
    * Supported operators:
    * - Comparison: =, !=, <, >, <=, >=, <> (not equal)
    * - Logical: AND, OR, NOT
@@ -298,7 +305,8 @@ export const RowLevelSecurityPolicySchema = z.object({
    * @example "status = 'active' AND expiry_date > NOW()"
    */
   using: z.string()
-    .describe('Filter condition (PostgreSQL SQL WHERE clause syntax with parameterized context variables)'),
+    .optional()
+    .describe('Filter condition for SELECT/UPDATE/DELETE (PostgreSQL SQL WHERE clause syntax with parameterized context variables). Optional for INSERT-only policies.'),
 
   /**
    * CHECK clause - Validation for INSERT/UPDATE operations.
@@ -373,6 +381,18 @@ export const RowLevelSecurityPolicySchema = z.object({
   tags: z.array(z.string())
     .optional()
     .describe('Policy categorization tags'),
+}).superRefine((data, ctx) => {
+  // Ensure at least one of USING or CHECK is provided
+  if (!data.using && !data.check) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: 'At least one of "using" or "check" must be specified. For SELECT/UPDATE/DELETE operations, provide "using". For INSERT operations, provide "check".',
+    });
+  }
+  
+  // For non-insert operations, USING should typically be present
+  // This is a soft warning through documentation, not enforced here
+  // since 'all' and mixed operation types are valid
 });
 
 /**