@gencow/core 0.1.14 → 0.1.16

package/dist/crud.d.ts

@@ -1,5 +1,5 @@
 /**
- * packages/core/src/crud.ts — Zero-Boilerplate CRUD API Auto-Generator (v2)
+ * packages/core/src/crud.ts — Zero-Boilerplate CRUD API Auto-Generator (v3)
  *
  * 사용자 코드 5줄로 완전한 CRUD API를 자동 생성:
  *
@@ -19,10 +19,11 @@
  * 내부적으로 query()/mutation()을 호출하여 글로벌 레지스트리에 등록하므로,
  * 프론트엔드에서 useQuery(api.tasks.list) / useMutation(api.tasks.create) 로 바로 사용 가능.
  *
- * 📄 Spec: docs/specs/spec-crud-v2-enhancements.md
+ * 📄 Spec: docs/specs/spec-crud-advanced-filters.md (v3), docs/specs/spec-crud-v2-enhancements.md (v2)
  * 📦 참조: saas-js/drizzle-crud 팩토리 패턴
  */
-import type { PgTable } from "drizzle-orm/pg-core";
+import { type SQL } from "drizzle-orm";
+import type { PgTable, AnyPgColumn } from "drizzle-orm/pg-core";
 type CrudOptions<T extends PgTable> = {
     /** 검색 대상 필드 — list의 search 파라미터에 사용 */
     searchFields?: (keyof T["_"]["columns"])[];
@@ -48,6 +49,37 @@ type CrudOptions<T extends PgTable> = {
     /** 키 접두사 오버라이드 (기본: 테이블명) */
     prefix?: string;
 };
+/** 지원 연산자 목록 */
+declare const FILTER_OPS: readonly ["eq", "ne", "gt", "gte", "lt", "lte", "in", "nin", "like", "ilike"];
+type FilterOp = typeof FILTER_OPS[number];
+/**
+ * 단일 필터 연산자를 Drizzle SQL 조건으로 변환.
+ * 지원하지 않는 op이거나 값 타입이 맞지 않으면 undefined 반환 (묵살).
+ */
+export declare function applyFilterOp(col: AnyPgColumn, op: FilterOp, value: unknown): SQL | undefined;
+/**
+ * 재귀적 필터 노드 파싱 — OR/AND 논리 중첩 + 연산자 매핑.
+ *
+ * @param node         - 필터 JSON 객체
+ * @param table        - Drizzle PgTable (컬럼 매핑)
+ * @param allowedFields - 허용 필드 화이트리스트 (미지정 시 모든 테이블 컬럼 허용)
+ *
+ * @example
+ * ```ts
+ * // 암묵적 eq (v2 하위호환)
+ * parseFilterNode({ status: 'active' }, table)
+ *   → and(eq(table.status, 'active'))
+ *
+ * // 명시적 연산자
+ * parseFilterNode({ qty: { op: 'gte', value: 10 } }, table)
+ *   → and(gte(table.qty, 10))
+ *
+ * // OR / AND 중첩
+ * parseFilterNode({ OR: [{ a: 1 }, { b: { op: 'gt', value: 5 } }] }, table)
+ *   → or(eq(table.a, 1), gt(table.b, 5))
+ * ```
+ */
+export declare function parseFilterNode(node: Record<string, unknown>, table: any, allowedFields?: readonly string[], depth?: number): SQL | undefined;
 /**
  * 테이블을 받아 query/mutation을 자동 등록하고,
  * { list, get, create, update, remove } 를 반환한다.

package/dist/crud.js

@@ -1,5 +1,5 @@
 /**
- * packages/core/src/crud.ts — Zero-Boilerplate CRUD API Auto-Generator (v2)
+ * packages/core/src/crud.ts — Zero-Boilerplate CRUD API Auto-Generator (v3)
  *
  * 사용자 코드 5줄로 완전한 CRUD API를 자동 생성:
  *
@@ -19,10 +19,10 @@
  * 내부적으로 query()/mutation()을 호출하여 글로벌 레지스트리에 등록하므로,
  * 프론트엔드에서 useQuery(api.tasks.list) / useMutation(api.tasks.create) 로 바로 사용 가능.
  *
- * 📄 Spec: docs/specs/spec-crud-v2-enhancements.md
+ * 📄 Spec: docs/specs/spec-crud-advanced-filters.md (v3), docs/specs/spec-crud-v2-enhancements.md (v2)
  * 📦 참조: saas-js/drizzle-crud 팩토리 패턴
  */
-import { eq, desc, asc, ilike, or, and, count as drizzleCount, getTableName } from "drizzle-orm";
+import { eq, ne, gt, gte, lt, lte, desc, asc, like, ilike, inArray, notInArray, or, and, count as drizzleCount, getTableName } from "drizzle-orm";
 import { query, mutation } from "./reactive";
 import { v } from "./v";
 // ─── Helpers ────────────────────────────────────────────
@@ -37,6 +37,119 @@ function detectIdType(column) {
         return v.string();
     return v.number();
 }
+// ─── v3 Filter Engine — 재귀적 동적 필터링 ──────────────
+/** 재귀 필터 최대 깊이 — DoS 방어 (깊이 초과 시 조건 묵살) */
+const MAX_FILTER_DEPTH = 5;
+/** 지원 연산자 목록 */
+const FILTER_OPS = ['eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'in', 'nin', 'like', 'ilike'];
+function isValidFilterOp(op) {
+    return FILTER_OPS.includes(op);
+}
+/**
+ * 단일 필터 연산자를 Drizzle SQL 조건으로 변환.
+ * 지원하지 않는 op이거나 값 타입이 맞지 않으면 undefined 반환 (묵살).
+ */
+export function applyFilterOp(col, op, value) {
+    switch (op) {
+        case 'eq': return eq(col, value);
+        case 'ne': return ne(col, value);
+        case 'gt': return gt(col, value);
+        case 'gte': return gte(col, value);
+        case 'lt': return lt(col, value);
+        case 'lte': return lte(col, value);
+        case 'in':
+            if (!Array.isArray(value) || value.length === 0)
+                return undefined;
+            return inArray(col, value);
+        case 'nin':
+            if (!Array.isArray(value) || value.length === 0)
+                return undefined;
+            return notInArray(col, value);
+        case 'like':
+            if (typeof value !== 'string')
+                return undefined;
+            return like(col, value);
+        case 'ilike':
+            if (typeof value !== 'string')
+                return undefined;
+            return ilike(col, value);
+        default: return undefined;
+    }
+}
+/**
+ * 재귀적 필터 노드 파싱 — OR/AND 논리 중첩 + 연산자 매핑.
+ *
+ * @param node         - 필터 JSON 객체
+ * @param table        - Drizzle PgTable (컬럼 매핑)
+ * @param allowedFields - 허용 필드 화이트리스트 (미지정 시 모든 테이블 컬럼 허용)
+ *
+ * @example
+ * ```ts
+ * // 암묵적 eq (v2 하위호환)
+ * parseFilterNode({ status: 'active' }, table)
+ *   → and(eq(table.status, 'active'))
+ *
+ * // 명시적 연산자
+ * parseFilterNode({ qty: { op: 'gte', value: 10 } }, table)
+ *   → and(gte(table.qty, 10))
+ *
+ * // OR / AND 중첩
+ * parseFilterNode({ OR: [{ a: 1 }, { b: { op: 'gt', value: 5 } }] }, table)
+ *   → or(eq(table.a, 1), gt(table.b, 5))
+ * ```
+ */
+export function parseFilterNode(node, table, allowedFields, depth = 0) {
+    // DoS 방어: 재귀 깊이 제한 초과 시 조건 묵살
+    if (depth > MAX_FILTER_DEPTH)
+        return undefined;
+    const conditions = [];
+    for (const [key, val] of Object.entries(node)) {
+        // ── OR 논리 그룹 ──
+        if (key === 'OR') {
+            if (!Array.isArray(val))
+                continue; // 잘못된 타입 → 묵살
+            const orConds = val
+                .filter((child) => child != null && typeof child === 'object' && !Array.isArray(child))
+                .map((child) => parseFilterNode(child, table, allowedFields, depth + 1))
+                .filter((c) => c !== undefined);
+            if (orConds.length > 0)
+                conditions.push(or(...orConds));
+            continue;
+        }
+        // ── AND 논리 그룹 ──
+        if (key === 'AND') {
+            if (!Array.isArray(val))
+                continue;
+            const andConds = val
+                .filter((child) => child != null && typeof child === 'object' && !Array.isArray(child))
+                .map((child) => parseFilterNode(child, table, allowedFields, depth + 1))
+                .filter((c) => c !== undefined);
+            if (andConds.length > 0)
+                conditions.push(and(...andConds));
+            continue;
+        }
+        // ── 컬럼 필터 ──
+        // allowedFields 화이트리스트 검증 (재귀적으로 OR/AND 내부에도 적용됨)
+        if (allowedFields && !allowedFields.includes(key))
+            continue;
+        const col = table[key];
+        if (!col)
+            continue;
+        // 명시적 연산자: { op: 'gte', value: 10 }
+        if (val != null && typeof val === 'object' && !Array.isArray(val) && 'op' in val) {
+            const { op, value } = val;
+            if (!isValidFilterOp(op))
+                continue; // 미지원 op → 묵살
+            const cond = applyFilterOp(col, op, value);
+            if (cond)
+                conditions.push(cond);
+            continue;
+        }
+        // 암묵적 eq (v2 하위호환): { status: 'active' } → eq(status, 'active')
+        conditions.push(eq(col, val));
+    }
+    return conditions.length > 0 ? and(...conditions) : undefined;
+}
 // ─── crud — Zero-Boilerplate API Factory ──────────
 /**
  * 테이블을 받아 query/mutation을 자동 등록하고,
@@ -82,14 +195,14 @@ export function crud(table, options) {
             const searchConds = options.searchFields.map((f) => ilike(anyTable[f], `%${args.search}%`));
             conditions.push(or(...searchConds));
         }
-        // Dynamic filters (allowedFilters 화이트리스트만 허용)
-        if (args?.filters && options?.allowedFilters?.length) {
-            for (const [key, value] of Object.entries(args.filters)) {
-                if (options.allowedFilters.includes(key) && anyTable[key]) {
-                    conditions.push(eq(anyTable[key], value));
-                }
-                // allowedFilters에 없는 키는 무시 (보안)
-            }
+        // Dynamic filters — v3 재귀적 파싱 엔진 (OR/AND 중첩, 연산자 매핑)
+        // allowedFilters 설정 시: 화이트리스트 필드만 허용 (재귀 검증)
+        // allowedFilters 미설정 시: 필터 전체 무시 (Secure by Default — v2 호환)
+        if (args?.filters && typeof args.filters === 'object' && options?.allowedFilters?.length) {
+            const allowedFields = options.allowedFilters;
+            const filterCondition = parseFilterNode(args.filters, anyTable, allowedFields);
+            if (filterCondition)
+                conditions.push(filterCondition);
         }
         return conditions.length > 0 ? and(...conditions) : undefined;
     }

package/dist/index.d.ts

@@ -19,5 +19,5 @@ export { defineAuth } from "./auth-config";
 export type { GencowAuthConfig, AuthEmailVerification } from "./auth-config";
 export { ownerRls } from "./rls";
 export { createRlsDb } from "./rls-db";
-export { crud } from "./crud";
+export { crud, parseFilterNode, applyFilterOp } from "./crud";
 export { crud as gencowCrud } from "./crud";

package/dist/index.js

@@ -13,6 +13,6 @@ export { defineAuth } from "./auth-config";
 // ─── RLS + CRUD Factory ───────────
 export { ownerRls } from "./rls";
 export { createRlsDb } from "./rls-db";
-export { crud } from "./crud";
+export { crud, parseFilterNode, applyFilterOp } from "./crud";
 // Deprecated alias — 하위호환용, 향후 메이저 버전에서 제거 예정
 export { crud as gencowCrud } from "./crud";

package/dist/reactive.d.ts

@@ -48,7 +48,7 @@ export interface AIResult {
     model: string;
 }
 export interface AIContext {
-    /** AI 텍스트 생성 — ctx.ai.chat({ model, messages }) */
+    /** AI 텍스트 생성 */
     chat: (opts: {
         model?: string;
         messages: AIMessage[];
@@ -61,9 +61,9 @@ export interface AIContext {
             type: string;
         };
     }) => Promise<AIResult>;
-    /** 텍스트 임베딩 (단일) — ctx.ai.embed("검색 텍스트") */
+    /** 텍스트 임베딩 (단일) */
     embed: (text: string) => Promise<number[]>;
-    /** 배치 임베딩 — ctx.ai.embedMany(["텍스트1", "텍스트2"]) */
+    /** 배치 임베딩 */
     embedMany: (texts: string[]) => Promise<number[][]>;
 }
 export interface GencowCtx {
@@ -81,7 +81,7 @@ export interface GencowCtx {
     realtime: RealtimeCtx;
     /** 재시도 — ctx.retry(fn, opts) — exponential backoff + jitter */
     retry: <T>(fn: () => Promise<T>, options?: import("./retry").RetryOptions) => Promise<T>;
-    /** AI 헬퍼 — ctx.ai.chat({ model, messages }) — 로컬: 직접 호출, BaaS: Control Plane 프록시 */
+    /** AI 헬퍼 */
     ai?: AIContext;
 }
 type QueryHandler<TArgs = any, TReturn = any> = (ctx: GencowCtx, args: TArgs) => Promise<TReturn>;
@@ -248,8 +248,18 @@ export declare function deregisterClient(ws: WSContext): void;
  * 마지막 데이터만 push하여 불필요한 전송을 방지합니다.
  *
  * ⚠️ 매 mutation 호출마다 새로 생성해야 합니다 (debounce timer가 mutation scope에 격리).
+ *
+ * @param options.httpCallback  BaaS 모드: Platform WS Gateway에 HTTP로 emit 전달.
+ *                              설정되면 WS 직접 push 대신 이 콜백을 호출.
+ *                              로컬 dev에서는 미설정 → 기존 WS 직접 push 유지.
  */
-export declare function buildRealtimeCtx(): RealtimeCtx;
+export declare function buildRealtimeCtx(options?: {
+    httpCallback?: (event: {
+        type: "emit";
+        queryKey: string;
+        data: unknown;
+    }) => void;
+}): RealtimeCtx;
 /**
  * mutation이 끝난 후 호출되는 legacy fallback.
  * `ctx.realtime.emit()`을 사용하는 새 mutation에서는 빈 배열([])을 전달하면 됩니다.
@@ -258,8 +268,9 @@ export declare function buildRealtimeCtx(): RealtimeCtx;
  * (서버에서 쿼리를 재실행하지 않으므로 DB 부하 없음)
  *
  * @deprecated ctx.realtime.emit() 사용 권장
+ * @param httpInvalidateCallback  BaaS 모드: Platform WS Gateway에 HTTP로 invalidation 전달.
  */
-export declare function invalidateQueries(queryKeys: string[], ctx: GencowCtx): Promise<void>;
+export declare function invalidateQueries(queryKeys: string[], ctx: GencowCtx, httpInvalidateCallback?: (queryKeys: string[]) => void): Promise<void>;
 export declare function handleWsMessage(ws: WSContext, raw: string | ArrayBuffer): void;
 export declare function getQueryHandler(key: string): QueryHandler | undefined;
 export declare function getQueryDef(key: string): QueryDef | undefined;

package/dist/reactive.js

@@ -181,8 +181,12 @@ export function deregisterClient(ws) {
  * 마지막 데이터만 push하여 불필요한 전송을 방지합니다.
  *
  * ⚠️ 매 mutation 호출마다 새로 생성해야 합니다 (debounce timer가 mutation scope에 격리).
+ *
+ * @param options.httpCallback  BaaS 모드: Platform WS Gateway에 HTTP로 emit 전달.
+ *                              설정되면 WS 직접 push 대신 이 콜백을 호출.
+ *                              로컬 dev에서는 미설정 → 기존 WS 직접 push 유지.
  */
-export function buildRealtimeCtx() {
+export function buildRealtimeCtx(options) {
     const pendingEmits = new Map();
     return {
         emit(queryKey, data) {
@@ -192,6 +196,12 @@ export function buildRealtimeCtx() {
                 clearTimeout(existing.timer);
             const timer = setTimeout(() => {
                 pendingEmits.delete(queryKey);
+                // BaaS 모드: Platform WS Gateway에 HTTP callback
+                if (options?.httpCallback) {
+                    options.httpCallback({ type: "emit", queryKey, data });
+                    return;
+                }
+                // 로컬 dev: WS 직접 push (기존 동작)
                 const clients = subscribers.get(queryKey);
                 if (!clients || clients.size === 0)
                     return;
@@ -221,11 +231,17 @@ export function buildRealtimeCtx() {
  * (서버에서 쿼리를 재실행하지 않으므로 DB 부하 없음)
  *
  * @deprecated ctx.realtime.emit() 사용 권장
+ * @param httpInvalidateCallback  BaaS 모드: Platform WS Gateway에 HTTP로 invalidation 전달.
  */
-export async function invalidateQueries(queryKeys, ctx) {
+export async function invalidateQueries(queryKeys, ctx, httpInvalidateCallback) {
     if (queryKeys.length === 0)
         return; // emit() 방식에서는 no-op
-    // invalidate 신호만 broadcast (re-fetch는 클라이언트 결정에 맡김)
+    // BaaS 모드: Platform WS Gateway에 HTTP callback
+    if (httpInvalidateCallback) {
+        httpInvalidateCallback(queryKeys);
+        return;
+    }
+    // 로컬 dev: WS 직접 broadcast (기존 동작)
     const invalidateMsg = JSON.stringify({ type: "invalidate", queries: queryKeys });
     for (const ws of connectedClients) {
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gencow/core",
-    "version": "0.1.14",
+    "version": "0.1.16",
     "description": "Gencow core library — defineQuery, defineMutation, reactive subscriptions",
     "type": "module",
     "main": "dist/index.js",

package/src/__tests__/crud.test.ts

@@ -26,7 +26,7 @@ import { pgTable, serial, text, timestamp } from "drizzle-orm/pg-core";
 
 // ─── crud import ───────────────────────────────────────────────────────
 
-import { crud } from "../crud";
+import { crud, parseFilterNode, applyFilterOp } from "../crud";
 
 // ─── 테스트 테이블 정의 ────────────────────────────────────────────────────
 
@@ -525,3 +525,423 @@ describe("crud() — allowedFilters", () => {
         expect(result2).toHaveProperty("data");
     });
 });
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 11. v3 Filter Engine — parseFilterNode 직접 테스트 (spec TC1~5)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+describe("v3 Filter Engine — parseFilterNode", () => {
+    // TC1: 하위 호환성 (Implicit eq)
+    it("TC1: 단순 key-value는 암묵적 eq로 파싱된다 (하위호환)", () => {
+        const table = pgTable("tc1_test", {
+            id: serial("id").primaryKey(),
+            status: text("status"),
+        });
+
+        const result = parseFilterNode({ status: "active" }, table);
+        expect(result).toBeDefined();
+    });
+
+    it("TC1: 여러 key-value 동시 사용 시 모두 AND 결합된다", () => {
+        const table = pgTable("tc1b_test", {
+            id: serial("id").primaryKey(),
+            status: text("status"),
+            category: text("category"),
+        });
+
+        const result = parseFilterNode({ status: "active", category: "tech" }, table);
+        expect(result).toBeDefined();
+    });
+
+    // TC2: 다중 논리망 (Nested OR & AND)
+    it("TC2: AND + 중첩 OR 필터가 SQL 조건으로 빌드된다", () => {
+        const table = pgTable("tc2_test", {
+            id: serial("id").primaryKey(),
+            category: text("category"),
+            qty: serial("qty"),
+            flag: text("flag"),
+        });
+
+        const result = parseFilterNode({
+            AND: [
+                { category: "A" },
+                { OR: [
+                    { qty: { op: "gte", value: 10 } },
+                    { flag: true },
+                ] },
+            ],
+        }, table);
+
+        expect(result).toBeDefined();
+    });
+
+    it("TC2: 단순 OR 배열도 파싱된다", () => {
+        const table = pgTable("tc2b_test", {
+            id: serial("id").primaryKey(),
+            title: text("title"),
+            description: text("description"),
+        });
+
+        const result = parseFilterNode({
+            OR: [
+                { title: { op: "ilike", value: "%AI%" } },
+                { description: { op: "ilike", value: "%데이터%" } },
+            ],
+        }, table);
+
+        expect(result).toBeDefined();
+    });
+
+    // TC3: 보안 방어 — allowedFilters 위반
+    it("TC3: allowedFilters에 없는 필드는 완전 묵살 (직접 접근)", () => {
+        const table = pgTable("tc3_test", {
+            id: serial("id").primaryKey(),
+            status: text("status"),
+            title: text("title"),
+            passwordHash: text("password_hash"),
+        });
+
+        // password_hash 직접 접근 → 묵살
+        const r1 = parseFilterNode(
+            { passwordHash: { op: "eq", value: "xxx" } },
+            table,
+            ["status", "title"],
+        );
+        expect(r1).toBeUndefined(); // 모든 조건 제거됨
+    });
+
+    it("TC3: OR 틈새 우회 시도 시 미허용 필드만 묵살, 허용 필드는 유지", () => {
+        const table = pgTable("tc3b_test", {
+            id: serial("id").primaryKey(),
+            status: text("status"),
+            isAdmin: text("is_admin"),
+        });
+
+        const r = parseFilterNode(
+            { OR: [{ status: "public" }, { isAdmin: true }] },
+            table,
+            ["status"],
+        );
+        // status는 허용 → OR 조건 살아있음
+        expect(r).toBeDefined();
+    });
+
+    it("TC3: 모든 필드가 미허용이면 undefined 반환", () => {
+        const table = pgTable("tc3c_test", {
+            id: serial("id").primaryKey(),
+            secret: text("secret"),
+        });
+
+        const r = parseFilterNode(
+            { OR: [{ secret: "hi" }] },
+            table,
+            ["status"],
+        );
+        expect(r).toBeUndefined();
+    });
+
+    // TC4: 악의적 페이로드 구조 방어
+    it("TC4: OR에 비배열 전달 시 무시, 크래시 없음", () => {
+        const table = pgTable("tc4_test", {
+            id: serial("id").primaryKey(),
+            age: serial("age"),
+        });
+
+        expect(parseFilterNode({ OR: "not-an-array" as any }, table)).toBeUndefined();
+    });
+
+    it("TC4: 미지원 op 키워드(DROP TABLE 등) 묵살, 크래시 없음", () => {
+        const table = pgTable("tc4b_test", {
+            id: serial("id").primaryKey(),
+            age: serial("age"),
+        });
+
+        expect(parseFilterNode({ age: { op: "DROP TABLE", value: 1 } }, table)).toBeUndefined();
+    });
+
+    it("TC4: AND에 null/string/number 등 비객체 원소 묵살", () => {
+        const table = pgTable("tc4c_test", {
+            id: serial("id").primaryKey(),
+        });
+
+        expect(parseFilterNode({ AND: [null, "string", 42] as any }, table)).toBeUndefined();
+        expect(parseFilterNode({ AND: null as any }, table)).toBeUndefined();
+    });
+
+    it("TC4: 존재하지 않는 컬럼명 필터는 묵살", () => {
+        const table = pgTable("tc4d_test", {
+            id: serial("id").primaryKey(),
+            name: text("name"),
+        });
+
+        const r = parseFilterNode({ nonExistentCol: "value" }, table);
+        expect(r).toBeUndefined();
+    });
+
+    // TC5: IN / NIN 연산자 배열값 처리
+    it("TC5: in 연산자 — 정상 배열은 SQL 생성", () => {
+        const table = pgTable("tc5_test", {
+            id: serial("id").primaryKey(),
+            status: text("status"),
+        });
+
+        const r = parseFilterNode({ id: { op: "in", value: [1, 2, 3] } }, table);
+        expect(r).toBeDefined();
+    });
+
+    it("TC5: in 연산자 — 비배열은 묵살", () => {
+        const table = pgTable("tc5b_test", {
+            id: serial("id").primaryKey(),
+        });
+
+        const r = parseFilterNode({ id: { op: "in", value: "1" } }, table);
+        expect(r).toBeUndefined();
+    });
+
+    it("TC5: in 연산자 — 빈 배열은 묵살", () => {
+        const table = pgTable("tc5c_test", {
+            id: serial("id").primaryKey(),
+        });
+
+        const r = parseFilterNode({ id: { op: "in", value: [] } }, table);
+        expect(r).toBeUndefined();
+    });
+
+    it("TC5: nin 연산자 — 정상 배열은 SQL 생성", () => {
+        const table = pgTable("tc5d_test", {
+            id: serial("id").primaryKey(),
+        });
+
+        const r = parseFilterNode({ id: { op: "nin", value: [10, 20] } }, table);
+        expect(r).toBeDefined();
+    });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 12. v3 Filter Engine — applyFilterOp 직접 테스트
+// ═══════════════════════════════════════════════════════════════════════════════
+
+describe("v3 Filter Engine — applyFilterOp", () => {
+    const table = pgTable("op_test", {
+        id: serial("id").primaryKey(),
+        name: text("name"),
+        age: serial("age"),
+    });
+
+    it("eq 연산자가 SQL 조건을 반환한다", () => {
+        expect(applyFilterOp(table.name, "eq", "test")).toBeDefined();
+    });
+
+    it("ne 연산자가 SQL 조건을 반환한다", () => {
+        expect(applyFilterOp(table.name, "ne", "test")).toBeDefined();
+    });
+
+    it("gt/gte/lt/lte 비교 연산자가 SQL 조건을 반환한다", () => {
+        expect(applyFilterOp(table.age, "gt", 10)).toBeDefined();
+        expect(applyFilterOp(table.age, "gte", 18)).toBeDefined();
+        expect(applyFilterOp(table.age, "lt", 100)).toBeDefined();
+        expect(applyFilterOp(table.age, "lte", 65)).toBeDefined();
+    });
+
+    it("like/ilike 패턴 연산자가 SQL 조건을 반환한다", () => {
+        expect(applyFilterOp(table.name, "like", "%test%")).toBeDefined();
+        expect(applyFilterOp(table.name, "ilike", "%TEST%")).toBeDefined();
+    });
+
+    it("in 연산자 — 정상 배열은 SQL 반환", () => {
+        expect(applyFilterOp(table.id, "in", [1, 2, 3])).toBeDefined();
+    });
+
+    it("nin 연산자 — 빈 배열은 undefined 반환", () => {
+        expect(applyFilterOp(table.id, "nin", [])).toBeUndefined();
+    });
+
+    it("미지원 연산자는 undefined 반환", () => {
+        expect(applyFilterOp(table.id, "INVALID" as any, 1)).toBeUndefined();
+    });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 13. v3 crud() handler 통합 테스트 — Advanced Filters
+// ═══════════════════════════════════════════════════════════════════════════════
+
+describe("v3 crud() — advanced filters through handler", () => {
+    it("allowedFilters 미설정 시 필터가 무시된다 (Secure by Default)", async () => {
+        const openTable = pgTable("v3_open_filter", {
+            id: serial("id").primaryKey(),
+            status: text("status"),
+            createdAt: timestamp("created_at").defaultNow(),
+        });
+
+        // allowedFilters 미설정 → 필터 전체 무시 (v2 호환, Secure by Default)
+        crud(openTable, { public: true });
+
+        const listDef = getQueryDef("v3_open_filter.list");
+        expect(listDef).toBeDefined();
+
+        const mockCtx = createListMockCtx([{ id: 1, status: "active" }]);
+        const result = await listDef!.handler(mockCtx, {
+            filters: { status: { op: "eq", value: "active" } },
+        });
+
+        // 필터가 무시되어도 에러 없이 정상 동작
+        expect(result).toHaveProperty("data");
+        expect(result).toHaveProperty("total");
+    });
+
+    it("allowedFilters 설정 시 v3 고급 필터가 동작한다", async () => {
+        const advTable = pgTable("v3_adv_filter", {
+            id: serial("id").primaryKey(),
+            status: text("status"),
+            createdAt: timestamp("created_at").defaultNow(),
+        });
+
+        crud(advTable, { public: true, allowedFilters: ["status"] });
+
+        const listDef = getQueryDef("v3_adv_filter.list");
+        const mockCtx = createListMockCtx([{ id: 1, status: "active" }]);
+        const result = await listDef!.handler(mockCtx, {
+            filters: { status: { op: "eq", value: "active" } },
+        });
+
+        expect(result).toHaveProperty("data");
+        expect(result).toHaveProperty("total");
+    });
+
+    it("복합 OR/AND 필터가 handler에서 에러 없이 실행된다", async () => {
+        const complexTable = pgTable("v3_complex", {
+            id: serial("id").primaryKey(),
+            title: text("title"),
+            status: text("status"),
+            createdAt: timestamp("created_at").defaultNow(),
+        });
+
+        crud(complexTable, { public: true, allowedFilters: ["title", "status"] });
+
+        const listDef = getQueryDef("v3_complex.list");
+        const mockCtx = createListMockCtx([]);
+
+        const result = await listDef!.handler(mockCtx, {
+            filters: {
+                OR: [
+                    { title: { op: "ilike", value: "%AI%" } },
+                    { status: { op: "in", value: ["active", "archived"] } },
+                ],
+            },
+        });
+
+        expect(result).toHaveProperty("data");
+        expect(result.total).toBe(0);
+    });
+
+    it("악성 페이로드가 handler를 크래시시키지 않는다", async () => {
+        const safeTable = pgTable("v3_safe", {
+            id: serial("id").primaryKey(),
+            name: text("name"),
+            createdAt: timestamp("created_at").defaultNow(),
+        });
+
+        crud(safeTable, { public: true });
+
+        const listDef = getQueryDef("v3_safe.list");
+        const mockCtx = createListMockCtx([{ id: 1 }]);
+
+        // 다양한 악성 페이로드 — 모두 에러 없이 실행
+        const payloads = [
+            { filters: { OR: "not-array" } },
+            { filters: { AND: null } },
+            { filters: { name: { op: "EVIL_OP", value: 1 } } },
+            { filters: { OR: [null, undefined, 42, "bad"] } },
+            { filters: {} },
+        ];
+
+        for (const payload of payloads) {
+            const result = await listDef!.handler(mockCtx, payload);
+            expect(result).toHaveProperty("data");
+            expect(result).toHaveProperty("total");
+        }
+    });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 14. v3 보안 강화 — 재귀 깊이 제한 + like/ilike 타입 검증
+// ═══════════════════════════════════════════════════════════════════════════════
+
+describe("v3 보안 강화 — 재귀 깊이 제한", () => {
+    it("MAX_FILTER_DEPTH(5) 초과 시 조건 묵살", () => {
+        const table = pgTable("depth_test", {
+            id: serial("id").primaryKey(),
+            name: text("name"),
+        });
+
+        // 깊이 6단계 중첩 — MAX_FILTER_DEPTH=5 초과
+        const deepFilter = {
+            OR: [{ AND: [{ OR: [{ AND: [{ OR: [{ AND: [{ name: "deep" }] }] }] }] }] }],
+        };
+
+        const result = parseFilterNode(deepFilter, table);
+        // 깊이 초과된 부분이 묵살되어 결과가 undefined이거나 부분 조건만 남음
+        // 중요한 것은 스택 오버플로 없이 정상 반환
+        expect(() => parseFilterNode(deepFilter, table)).not.toThrow();
+    });
+
+    it("MAX_FILTER_DEPTH 이내의 중첩은 정상 동작", () => {
+        const table = pgTable("depth_ok_test", {
+            id: serial("id").primaryKey(),
+            name: text("name"),
+            status: text("status"),
+        });
+
+        // 깊이 3단계 — 정상 범위
+        const normalFilter = {
+            OR: [
+                { AND: [{ OR: [{ name: "test" }] }] },
+                { status: "active" },
+            ],
+        };
+
+        const result = parseFilterNode(normalFilter, table);
+        expect(result).toBeDefined();
+    });
+
+    it("극단적 깊이(100단계)에서도 크래시 없음", () => {
+        const table = pgTable("depth_extreme_test", {
+            id: serial("id").primaryKey(),
+            name: text("name"),
+        });
+
+        // 100단계 중첩 생성
+        let filter: any = { name: "leaf" };
+        for (let i = 0; i < 100; i++) {
+            filter = i % 2 === 0 ? { OR: [filter] } : { AND: [filter] };
+        }
+
+        expect(() => parseFilterNode(filter, table)).not.toThrow();
+        // 깊이 초과로 조건 묵살 → undefined
+        const result = parseFilterNode(filter, table);
+        expect(result).toBeUndefined();
+    });
+});
+
+describe("v3 보안 강화 — like/ilike 타입 검증", () => {
+    const table = pgTable("like_type_test", {
+        id: serial("id").primaryKey(),
+        name: text("name"),
+    });
+
+    it("like에 문자열이 아닌 값 전달 시 undefined 반환", () => {
+        expect(applyFilterOp(table.name, "like", 12345)).toBeUndefined();
+        expect(applyFilterOp(table.name, "like", null)).toBeUndefined();
+        expect(applyFilterOp(table.name, "like", { evil: true })).toBeUndefined();
+    });
+
+    it("ilike에 문자열이 아닌 값 전달 시 undefined 반환", () => {
+        expect(applyFilterOp(table.name, "ilike", 99)).toBeUndefined();
+        expect(applyFilterOp(table.name, "ilike", ["array"])).toBeUndefined();
+    });
+
+    it("like/ilike에 정상 문자열 전달 시 SQL 반환", () => {
+        expect(applyFilterOp(table.name, "like", "%test%")).toBeDefined();
+        expect(applyFilterOp(table.name, "ilike", "%TEST%")).toBeDefined();
+    });
+});

package/src/crud.ts

@@ -1,5 +1,5 @@
 /**
- * packages/core/src/crud.ts — Zero-Boilerplate CRUD API Auto-Generator (v2)
+ * packages/core/src/crud.ts — Zero-Boilerplate CRUD API Auto-Generator (v3)
  *
  * 사용자 코드 5줄로 완전한 CRUD API를 자동 생성:
  *
@@ -19,11 +19,11 @@
  * 내부적으로 query()/mutation()을 호출하여 글로벌 레지스트리에 등록하므로,
  * 프론트엔드에서 useQuery(api.tasks.list) / useMutation(api.tasks.create) 로 바로 사용 가능.
  *
- * 📄 Spec: docs/specs/spec-crud-v2-enhancements.md
+ * 📄 Spec: docs/specs/spec-crud-advanced-filters.md (v3), docs/specs/spec-crud-v2-enhancements.md (v2)
  * 📦 참조: saas-js/drizzle-crud 팩토리 패턴
  */
 
-import { eq, desc, asc, ilike, or, and, count as drizzleCount, getTableName, getTableColumns, type SQL } from "drizzle-orm";
+import { eq, ne, gt, gte, lt, lte, desc, asc, like, ilike, inArray, notInArray, or, and, count as drizzleCount, getTableName, getTableColumns, type SQL } from "drizzle-orm";
 import type { PgTable, AnyPgColumn } from "drizzle-orm/pg-core";
 import { query, mutation } from "./reactive";
 import { v } from "./v";
@@ -67,6 +67,128 @@ function detectIdType(column: AnyPgColumn) {
     return v.number();
 }
 
+// ─── v3 Filter Engine — 재귀적 동적 필터링 ──────────────
+
+/** 재귀 필터 최대 깊이 — DoS 방어 (깊이 초과 시 조건 묵살) */
+const MAX_FILTER_DEPTH = 5;
+
+/** 지원 연산자 목록 */
+const FILTER_OPS = ['eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'in', 'nin', 'like', 'ilike'] as const;
+type FilterOp = typeof FILTER_OPS[number];
+
+function isValidFilterOp(op: string): op is FilterOp {
+    return (FILTER_OPS as readonly string[]).includes(op);
+}
+
+/**
+ * 단일 필터 연산자를 Drizzle SQL 조건으로 변환.
+ * 지원하지 않는 op이거나 값 타입이 맞지 않으면 undefined 반환 (묵살).
+ */
+export function applyFilterOp(col: AnyPgColumn, op: FilterOp, value: unknown): SQL | undefined {
+    switch (op) {
+        case 'eq':    return eq(col, value);
+        case 'ne':    return ne(col, value);
+        case 'gt':    return gt(col, value as any);
+        case 'gte':   return gte(col, value as any);
+        case 'lt':    return lt(col, value as any);
+        case 'lte':   return lte(col, value as any);
+        case 'in':
+            if (!Array.isArray(value) || value.length === 0) return undefined;
+            return inArray(col, value);
+        case 'nin':
+            if (!Array.isArray(value) || value.length === 0) return undefined;
+            return notInArray(col, value);
+        case 'like':
+            if (typeof value !== 'string') return undefined;
+            return like(col, value);
+        case 'ilike':
+            if (typeof value !== 'string') return undefined;
+            return ilike(col, value);
+        default:      return undefined;
+    }
+}
+
+/**
+ * 재귀적 필터 노드 파싱 — OR/AND 논리 중첩 + 연산자 매핑.
+ *
+ * @param node         - 필터 JSON 객체
+ * @param table        - Drizzle PgTable (컬럼 매핑)
+ * @param allowedFields - 허용 필드 화이트리스트 (미지정 시 모든 테이블 컬럼 허용)
+ *
+ * @example
+ * ```ts
+ * // 암묵적 eq (v2 하위호환)
+ * parseFilterNode({ status: 'active' }, table)
+ *   → and(eq(table.status, 'active'))
+ *
+ * // 명시적 연산자
+ * parseFilterNode({ qty: { op: 'gte', value: 10 } }, table)
+ *   → and(gte(table.qty, 10))
+ *
+ * // OR / AND 중첩
+ * parseFilterNode({ OR: [{ a: 1 }, { b: { op: 'gt', value: 5 } }] }, table)
+ *   → or(eq(table.a, 1), gt(table.b, 5))
+ * ```
+ */
+export function parseFilterNode(
+    node: Record<string, unknown>,
+    table: any,
+    allowedFields?: readonly string[],
+    depth: number = 0,
+): SQL | undefined {
+    // DoS 방어: 재귀 깊이 제한 초과 시 조건 묵살
+    if (depth > MAX_FILTER_DEPTH) return undefined;
+
+    const conditions: SQL[] = [];
+
+    for (const [key, val] of Object.entries(node)) {
+        // ── OR 논리 그룹 ──
+        if (key === 'OR') {
+            if (!Array.isArray(val)) continue; // 잘못된 타입 → 묵살
+            const orConds = val
+                .filter((child): child is Record<string, unknown> =>
+                    child != null && typeof child === 'object' && !Array.isArray(child))
+                .map((child) => parseFilterNode(child, table, allowedFields, depth + 1))
+                .filter((c): c is SQL => c !== undefined);
+            if (orConds.length > 0) conditions.push(or(...orConds)!);
+            continue;
+        }
+
+        // ── AND 논리 그룹 ──
+        if (key === 'AND') {
+            if (!Array.isArray(val)) continue;
+            const andConds = val
+                .filter((child): child is Record<string, unknown> =>
+                    child != null && typeof child === 'object' && !Array.isArray(child))
+                .map((child) => parseFilterNode(child, table, allowedFields, depth + 1))
+                .filter((c): c is SQL => c !== undefined);
+            if (andConds.length > 0) conditions.push(and(...andConds)!);
+            continue;
+        }
+
+        // ── 컬럼 필터 ──
+        // allowedFields 화이트리스트 검증 (재귀적으로 OR/AND 내부에도 적용됨)
+        if (allowedFields && !allowedFields.includes(key)) continue;
+
+        const col = table[key] as AnyPgColumn | undefined;
+        if (!col) continue;
+
+        // 명시적 연산자: { op: 'gte', value: 10 }
+        if (val != null && typeof val === 'object' && !Array.isArray(val) && 'op' in val) {
+            const { op, value } = val as { op: string; value: unknown };
+            if (!isValidFilterOp(op)) continue; // 미지원 op → 묵살
+            const cond = applyFilterOp(col, op, value);
+            if (cond) conditions.push(cond);
+            continue;
+        }
+
+        // 암묵적 eq (v2 하위호환): { status: 'active' } → eq(status, 'active')
+        conditions.push(eq(col, val));
+    }
+
+    return conditions.length > 0 ? and(...conditions) : undefined;
+}
+
 // ─── crud — Zero-Boilerplate API Factory ──────────
 
 /**
@@ -123,14 +245,17 @@ export function crud<T extends PgTable>(table: T, options?: CrudOptions<T>) {
             conditions.push(or(...searchConds)!);
         }
 
-        // Dynamic filters (allowedFilters 화이트리스트만 허용)
-        if (args?.filters && options?.allowedFilters?.length) {
-            for (const [key, value] of Object.entries(args.filters as Record<string, unknown>)) {
-                if (options.allowedFilters.includes(key as any) && anyTable[key]) {
-                    conditions.push(eq(anyTable[key] as AnyPgColumn, value));
-                }
-                // allowedFilters에 없는 키는 무시 (보안)
-            }
+        // Dynamic filters — v3 재귀적 파싱 엔진 (OR/AND 중첩, 연산자 매핑)
+        // allowedFilters 설정 시: 화이트리스트 필드만 허용 (재귀 검증)
+        // allowedFilters 미설정 시: 필터 전체 무시 (Secure by Default — v2 호환)
+        if (args?.filters && typeof args.filters === 'object' && options?.allowedFilters?.length) {
+            const allowedFields = options.allowedFilters as unknown as string[];
+            const filterCondition = parseFilterNode(
+                args.filters as Record<string, unknown>,
+                anyTable,
+                allowedFields,
+            );
+            if (filterCondition) conditions.push(filterCondition);
         }
 
         return conditions.length > 0 ? and(...conditions) : undefined;

package/src/index.ts

@@ -22,7 +22,7 @@ export type { GencowAuthConfig, AuthEmailVerification } from "./auth-config";
 // ─── RLS + CRUD Factory ───────────
 export { ownerRls } from "./rls";
 export { createRlsDb } from "./rls-db";
-export { crud } from "./crud";
+export { crud, parseFilterNode, applyFilterOp } from "./crud";
 
 // Deprecated alias — 하위호환용, 향후 메이저 버전에서 제거 예정
 export { crud as gencowCrud } from "./crud";

package/src/reactive.ts

@@ -54,7 +54,7 @@ export interface AIResult {
 }
 
 export interface AIContext {
-    /** AI 텍스트 생성 — ctx.ai.chat({ model, messages }) */
+    /** AI 텍스트 생성 */
     chat: (opts: {
         model?: string;
         messages: AIMessage[];
@@ -65,9 +65,9 @@ export interface AIContext {
         /** Response format — e.g. { type: "json_object" } for JSON mode */
         responseFormat?: { type: string };
     }) => Promise<AIResult>;
-    /** 텍스트 임베딩 (단일) — ctx.ai.embed("검색 텍스트") */
+    /** 텍스트 임베딩 (단일) */
     embed: (text: string) => Promise<number[]>;
-    /** 배치 임베딩 — ctx.ai.embedMany(["텍스트1", "텍스트2"]) */
+    /** 배치 임베딩 */
     embedMany: (texts: string[]) => Promise<number[][]>;
 }
 
@@ -86,7 +86,7 @@ export interface GencowCtx {
     realtime: RealtimeCtx;
     /** 재시도 — ctx.retry(fn, opts) — exponential backoff + jitter */
     retry: <T>(fn: () => Promise<T>, options?: import("./retry").RetryOptions) => Promise<T>;
-    /** AI 헬퍼 — ctx.ai.chat({ model, messages }) — 로컬: 직접 호출, BaaS: Control Plane 프록시 */
+    /** AI 헬퍼 */
     ai?: AIContext;
 }
 
@@ -392,8 +392,14 @@ export function deregisterClient(ws: WSContext) {
  * 마지막 데이터만 push하여 불필요한 전송을 방지합니다.
  *
  * ⚠️ 매 mutation 호출마다 새로 생성해야 합니다 (debounce timer가 mutation scope에 격리).
+ *
+ * @param options.httpCallback  BaaS 모드: Platform WS Gateway에 HTTP로 emit 전달.
+ *                              설정되면 WS 직접 push 대신 이 콜백을 호출.
+ *                              로컬 dev에서는 미설정 → 기존 WS 직접 push 유지.
  */
-export function buildRealtimeCtx(): RealtimeCtx {
+export function buildRealtimeCtx(options?: {
+    httpCallback?: (event: { type: "emit"; queryKey: string; data: unknown }) => void;
+}): RealtimeCtx {
     const pendingEmits = new Map<string, { data: unknown; timer: ReturnType<typeof setTimeout> }>();
 
     return {
@@ -404,6 +410,14 @@ export function buildRealtimeCtx(): RealtimeCtx {
 
             const timer = setTimeout(() => {
                 pendingEmits.delete(queryKey);
+
+                // BaaS 모드: Platform WS Gateway에 HTTP callback
+                if (options?.httpCallback) {
+                    options.httpCallback({ type: "emit", queryKey, data });
+                    return;
+                }
+
+                // 로컬 dev: WS 직접 push (기존 동작)
                 const clients = subscribers.get(queryKey);
                 if (!clients || clients.size === 0) return;
 
@@ -430,14 +444,22 @@ export function buildRealtimeCtx(): RealtimeCtx {
  * (서버에서 쿼리를 재실행하지 않으므로 DB 부하 없음)
  *
  * @deprecated ctx.realtime.emit() 사용 권장
+ * @param httpInvalidateCallback  BaaS 모드: Platform WS Gateway에 HTTP로 invalidation 전달.
  */
 export async function invalidateQueries(
     queryKeys: string[],
-    ctx: GencowCtx
+    ctx: GencowCtx,
+    httpInvalidateCallback?: (queryKeys: string[]) => void,
 ): Promise<void> {
     if (queryKeys.length === 0) return; // emit() 방식에서는 no-op
 
-    // invalidate 신호만 broadcast (re-fetch는 클라이언트 결정에 맡김)
+    // BaaS 모드: Platform WS Gateway에 HTTP callback
+    if (httpInvalidateCallback) {
+        httpInvalidateCallback(queryKeys);
+        return;
+    }
+
+    // 로컬 dev: WS 직접 broadcast (기존 동작)
     const invalidateMsg = JSON.stringify({ type: "invalidate", queries: queryKeys });
     for (const ws of connectedClients) {
         try { ws.send(invalidateMsg); } catch { connectedClients.delete(ws); }