@gencow/core 0.1.18 → 0.1.21

package/src/crud.ts

@@ -12,6 +12,17 @@
  * export const { list, get, create, update, remove } = crud(tasks);
  * ```
  *
+ * ownerRls 연동 (2-Layer 방어):
+ * ```ts
+ * export const tasks = pgTable("tasks", {
+ *     id: serial("id").primaryKey(),
+ *     userId: text("user_id").notNull(),
+ * }, (t) => ownerRls(t.userId));
+ *
+ * // crud()가 ownerRls를 자동 감지 → 모든 쿼리에 WHERE userId = auth.userId 주입
+ * export const { list, get, create, update, remove } = crud(tasks);
+ * ```
+ *
  * list 반환값: `{ data: T[], total: number }`
  *   → 프론트: `const result = useQuery(api.tasks.list); result?.data.map(...)`
  *   → total은 동일 필터 조건의 전체 레코드 수 (페이지네이션 UI 지원)
@@ -20,13 +31,26 @@
  * 프론트엔드에서 useQuery(api.tasks.list) / useMutation(api.tasks.create) 로 바로 사용 가능.
  *
  * 📄 Spec: docs/specs/spec-crud-advanced-filters.md (v3), docs/specs/spec-crud-v2-enhancements.md (v2)
+ * 📄 ownerRls: docs/specs/spec-ownerrls-complete.md
  * 📦 참조: saas-js/drizzle-crud 팩토리 패턴
  */
 
 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 { getTableConfig } from "drizzle-orm/pg-core";
 import { query, mutation } from "./reactive";
 import { v } from "./v";
+import { getOwnerRlsMeta, registerOwnerRls } from "./rls";
+
+// ─── ownerRls 감지 추적 (부트 로그용) ──────────────────
+
+/** crud()가 ownerRls를 자동 감지한 테이블 목록 — 서버 부트 로그에서 출력 */
+const _ownerRlsTables: { tableName: string; columnName: string; readPublic: boolean }[] = [];
+
+/** 부트 로그에서 ownerRls 감지 테이블 목록을 반환 */
+export function getOwnerRlsTables(): readonly { tableName: string; columnName: string; readPublic: boolean }[] {
+    return _ownerRlsTables;
+}
 
 // ─── Types ──────────────────────────────────────────────
 
@@ -74,6 +98,93 @@ function detectIdType(column: AnyPgColumn) {
     return v.number();
 }
 
+// ─── ownerRls 감지 ──────────────────────────────────────
+
+interface OwnerMetaResolved {
+    /** userId 역할을 하는 Drizzle 컬럼 참조 (WHERE 조건에 사용) */
+    column: AnyPgColumn;
+    /** userId 컬럼의 DB 이름 (e.g. "user_id") */
+    columnName: string;
+    /** userId 컬럼의 JS 프로퍼티 이름 (e.g. "userId" — INSERT/UPDATE 데이터 키에 사용) */
+    propertyName: string;
+    /** true면 SELECT에 userId 필터 생략 (누구나 읽기 가능) */
+    readPublic: boolean;
+}
+
+/**
+ * DB 컬럼명에서 JS 프로퍼티명을 역매핑한다.
+ * getTableColumns()의 키(JS명) → 값(Column.name = DB명) 매핑을 탐색.
+ * 매칭 실패 시 columnName을 그대로 반환 (best-effort).
+ */
+function resolvePropertyName(table: PgTable, columnName: string): string {
+    try {
+        const columns = getTableColumns(table);
+        for (const [propName, col] of Object.entries(columns)) {
+            if ((col as any).name === columnName) return propName;
+        }
+    } catch {
+        // 테스트 환경에서 getTableColumns 실패 가능 — fallback
+    }
+    return columnName;
+}
+
+/**
+ * 테이블에서 ownerRls 메타데이터를 감지한다.
+ *
+ * 감지 순서:
+ *   1. WeakMap 레지스트리 (registerOwnerRls로 명시 등록된 경우)
+ *   2. getTableConfig().policies에서 pgPolicy 존재 여부 + 컬럼 convention
+ *
+ * Fallback convention: 테이블에 userId/user_id 컬럼이 있고 pgPolicy가 존재하면
+ * ownerRls가 적용된 것으로 간주.
+ */
+function detectOwnerMeta(table: PgTable): OwnerMetaResolved | null {
+    const anyTable = table as any;
+
+    // 1. WeakMap 레지스트리에서 조회 (가장 정확)
+    const meta = getOwnerRlsMeta(table);
+    if (meta) {
+        // propertyName 역매핑: DB명 "user_id" → JS명 "userId"
+        const propName = resolvePropertyName(table, meta.columnName);
+        const col = anyTable[propName] as AnyPgColumn | undefined;
+        if (col) {
+            return { column: col, columnName: meta.columnName, propertyName: propName, readPublic: meta.readPublic };
+        }
+    }
+
+    // 2. getTableConfig().policies로 pgPolicy 존재 감지 + convention 탐색
+    try {
+        const config = getTableConfig(table);
+        if (config.policies && config.policies.length > 0) {
+            // convention: userId 또는 user_id 컬럼 탐색 (JS 프로퍼티명)
+            const propName = anyTable["userId"] ? "userId" : anyTable["user_id"] ? "user_id" : null;
+            if (propName) {
+                const userIdCol = anyTable[propName] as AnyPgColumn;
+                const colName = (userIdCol as any).name || "user_id";
+
+                // 테이블에 메타 등록 (이후 호출에서 WeakMap으로 빠르게 조회)
+                registerOwnerRls(table, { columnName: colName, readPublic: false });
+
+                return { column: userIdCol, columnName: colName, propertyName: propName, readPublic: false };
+            }
+
+            // S2 방어: pgPolicy가 존재하지만 convention 컬럼(userId/user_id)이 없는 경우
+            // ownerRls()를 호출했으나 비표준 컬럼명(e.g. ownerId, authorId)을 사용한 것으로 의심
+            // → silent 무시 방지: 보안 경고 출력
+            const tblName = getTableName(table);
+            console.warn(
+                `[crud] ⚠️ Table "${tblName}" has ${config.policies.length} pgPolicy but no userId/user_id column found. ` +
+                `ownerRls auto-isolation will NOT be applied. ` +
+                `If you used ownerRls(), ensure the column is named 'userId' (JS) / 'user_id' (DB).`
+            );
+        }
+    } catch {
+        // getTableConfig 실패 시 무시 (테스트 환경 등)
+    }
+
+    return null;
+}
+
 // ─── v3 Filter Engine — 재귀적 동적 필터링 ──────────────
 
 /** 재귀 필터 최대 깊이 — DoS 방어 (깊이 초과 시 조건 묵살) */
@@ -231,9 +342,33 @@ export function crud<T extends PgTable>(table: T, options?: CrudOptions<T>) {
     const createdAtCol = anyTable["createdAt"] as AnyPgColumn | undefined;
     const defaultOrderCol = createdAtCol || pk;
 
-    // userId 컬럼 (자동 주입용)
+    // userId 컬럼 (자동 주입용 — ownerRls 미적용 시 기존 동작)
     const userIdCol = anyTable["userId"] as AnyPgColumn | undefined;
 
+    // ── ownerRls 감지: 2-Layer 방어의 Layer 1 ──
+    // ownerRls() 메타데이터가 감지되면 모든 CRUD에 userId 필터 자동 주입
+    const ownerMeta = detectOwnerMeta(table);
+
+    // 부트 로그용 레지스트리 등록 (S1: 중복 방지 — hot-reload/methods 분할 대응)
+    if (ownerMeta && !_ownerRlsTables.some(t => t.tableName === tableName)) {
+        _ownerRlsTables.push({
+            tableName,
+            columnName: ownerMeta.columnName,
+            readPublic: ownerMeta.readPublic,
+        });
+    }
+
+    // B1: public + ownerRls 조합 방어
+    // ownerRls가 감지된 테이블에서 public: true + readPublic: false 조합은
+    // 보안 의도와 모순 → 경고 출력 + CUD는 ownerRls 보호 유지
+    if (ownerMeta && isPublic && !ownerMeta.readPublic) {
+        console.warn(
+            `[crud] ⚠️ Table "${tableName}": ownerRls detected but public=true. ` +
+            `CUD operations will still enforce ownerRls (auth required). ` +
+            `Consider removing { public: true } or using ownerRls(col, { read: "public" }).`
+        );
+    }
+
     // ── 내부 헬퍼: WHERE 조건 빌드 (list + count + realtime 공유) ──
     function buildWhereConditions(args: any): SQL | undefined {
         const conditions: SQL[] = [];
@@ -268,14 +403,31 @@ export function crud<T extends PgTable>(table: T, options?: CrudOptions<T>) {
         return conditions.length > 0 ? and(...conditions) : undefined;
     }
 
+    /** Uses `db.transaction` when present (e.g. createRlsDb); else runs `fn(db)` for test mocks without `.transaction`. */
+    async function inRlsOrPlainTx<T>(db: any, fn: (tx: any) => Promise<T>): Promise<T> {
+        if (typeof db?.transaction === "function") {
+            return await db.transaction(fn);
+        }
+        return await fn(db);
+    }
+
     // ── 내부 헬퍼: list+count 데이터 가져오기 (realtime push용 재사용) ──
-    // 순차 실행: 소규모 커넥션 풀 환경에서 동시 점유 방지
+    // Runs inside db.transaction so createRlsDb() can SET LOCAL app.current_user_id for RLS.
     // ⚠️ limit/offset 없이 전체 SELECT — 대량 데이터 시 성능 저하 주의
     // TODO(P2): realtime emit 시 invalidation 메시지만 전송하고 클라이언트가 re-fetch하는 패턴 검토
-    async function fetchListWithTotal(db: any, whereClause?: SQL) {
-        const data = await db.select().from(anyTable).where(whereClause).orderBy(desc(defaultOrderCol));
-        const countResult = await db.select({ count: drizzleCount() }).from(anyTable).where(whereClause);
-        return { data, total: Number(countResult[0]?.count ?? 0) };
+    async function fetchListWithTotal(db: any, whereClause?: SQL, userId?: string) {
+        // ownerRls 적용 시 realtime emit에도 userId 필터 추가
+        // → 다른 사용자에게 타인 데이터가 push되지 않도록
+        let effectiveWhere = whereClause;
+        if (ownerMeta && userId && !ownerMeta.readPublic) {
+            const ownerFilter = eq(ownerMeta.column, userId);
+            effectiveWhere = effectiveWhere ? and(effectiveWhere, ownerFilter) : ownerFilter;
+        }
+        return await inRlsOrPlainTx(db, async (tx: any) => {
+            const data = await tx.select().from(anyTable).where(effectiveWhere).orderBy(desc(defaultOrderCol));
+            const countResult = await tx.select({ count: drizzleCount() }).from(anyTable).where(effectiveWhere);
+            return { data, total: Number(countResult[0]?.count ?? 0) };
+        });
     }
 
     // ── methods 필터링: 지정된 메서드만 레지스트리 등록 ──
@@ -295,13 +447,21 @@ export function crud<T extends PgTable>(table: T, options?: CrudOptions<T>) {
             filters: v.optional(v.any()),
         },
         handler: async (ctx: any, args: any) => {
-            if (!isPublic) ctx.auth.requireAuth();
+            // S2: requireAuth 통합 — ownerRls(readPublic=false)이면 인증 필수
+            const needsAuth = !isPublic || (ownerMeta && !ownerMeta.readPublic);
+            const user = needsAuth ? ctx.auth.requireAuth() : null;
 
             const page = Math.max(1, args?.page || 1);
             const limit = Math.min(Math.max(1, args?.limit || defaultLimit), maxLimit);
             const offset = (page - 1) * limit;
 
-            const whereClause = buildWhereConditions(args);
+            let whereClause = buildWhereConditions(args);
+
+            // ── ownerRls Layer 1: list에 userId 필터 주입 ──
+            if (ownerMeta && !ownerMeta.readPublic && user) {
+                const ownerFilter = eq(ownerMeta.column, user.id);
+                whereClause = whereClause ? and(whereClause, ownerFilter) : ownerFilter;
+            }
 
             // Order
             let orderByClause;
@@ -312,21 +472,23 @@ export function crud<T extends PgTable>(table: T, options?: CrudOptions<T>) {
                 orderByClause = desc(defaultOrderCol);
             }
 
-            // SELECT + COUNT 순차 실행 — 소규모 커넥션 풀 환경에서 동시 점유 방지
-            const results = await ctx.db.select()
-                .from(anyTable)
-                .where(whereClause)
-                .orderBy(orderByClause)
-                .limit(limit)
-                .offset(offset);
-            const countResult = await ctx.db.select({ count: drizzleCount() })
-                .from(anyTable)
-                .where(whereClause);
-
-            return {
-                data: results,
-                total: Number(countResult[0]?.count ?? 0),
-            };
+            // One transaction: SET LOCAL user id (createRlsDb) + list + count for RLS.
+            return await inRlsOrPlainTx(ctx.db, async (tx: any) => {
+                const results = await tx.select()
+                    .from(anyTable)
+                    .where(whereClause)
+                    .orderBy(orderByClause)
+                    .limit(limit)
+                    .offset(offset);
+                const countResult = await tx.select({ count: drizzleCount() })
+                    .from(anyTable)
+                    .where(whereClause);
+
+                return {
+                    data: results,
+                    total: Number(countResult[0]?.count ?? 0),
+                };
+            });
         }
     });
 
@@ -336,17 +498,26 @@ export function crud<T extends PgTable>(table: T, options?: CrudOptions<T>) {
         public: isPublic,
         args: { id: idValidator },
         handler: async (ctx: any, args: any) => {
-            if (!isPublic) ctx.auth.requireAuth();
+            // S2: requireAuth 통합
+            const needsAuth = !isPublic || (ownerMeta && !ownerMeta.readPublic);
+            const user = needsAuth ? ctx.auth.requireAuth() : null;
 
             let whereCond: SQL = eq(pk, args.id);
 
+            // ── ownerRls Layer 1: get에 userId 필터 주입 ──
+            if (ownerMeta && !ownerMeta.readPublic && user) {
+                whereCond = and(whereCond, eq(ownerMeta.column, user.id))!;
+            }
+
             if (options?.softDelete) {
                 const sdField = anyTable[options.softDelete.field as string] as AnyPgColumn;
                 whereCond = and(whereCond, eq(sdField, null as any))!;
             }
 
-            const [result] = await ctx.db.select().from(anyTable).where(whereCond).limit(1);
-            return result ?? null;
+            return await inRlsOrPlainTx(ctx.db, async (tx: any) => {
+                const [result] = await tx.select().from(anyTable).where(whereCond).limit(1);
+                return result ?? null;
+            });
         }
     });
 
@@ -355,12 +526,29 @@ export function crud<T extends PgTable>(table: T, options?: CrudOptions<T>) {
     const createDef = !enabledMethods.has('create') ? undefined : mutation(`${prefix}.create`, {
         public: isPublic,
         handler: async (ctx: any, args: any) => {
-            const user = isPublic ? null : ctx.auth.requireAuth();
+            // ownerRls 테이블은 항상 인증 필수 (보안 우선)
+            const user = (ownerMeta || !isPublic) ? ctx.auth.requireAuth() : null;
 
             let insertData = { ...args };
 
-            // userId 자동 주입 (테이블에 userId 컬럼이 있고 인증된 경우)
-            if (userIdCol && user && !insertData.userId) {
+            // ── ownerRls Layer 1: create 시 userId 강제 주입 ──
+            // 명시적으로 타인 userId를 보낸 경우는 즉시 차단 (fail-closed).
+            if (ownerMeta && user) {
+                const requestedOwner =
+                    insertData[ownerMeta.propertyName] ??
+                    insertData[ownerMeta.columnName] ??
+                    insertData.userId;
+                if (requestedOwner != null && requestedOwner !== user.id) {
+                    throw new Error("Forbidden: cannot create resource for another user");
+                }
+            }
+
+            // S1 수정: propertyName(JS명)을 키로 사용 — Drizzle insert 호환
+            // 사용자 입력을 덮어씀 (보안: 타인 ID로 데이터 생성 방지)
+            if (ownerMeta && user) {
+                insertData[ownerMeta.propertyName] = user.id;
+            } else if (userIdCol && user && !insertData.userId) {
+                // ownerRls 미적용 테이블의 기존 자동 주입 동작 유지
                 insertData.userId = user.id;
             }
 
@@ -369,11 +557,16 @@ export function crud<T extends PgTable>(table: T, options?: CrudOptions<T>) {
                 insertData = await options.hooks.beforeCreate(insertData);
             }
 
-            const [result] = await ctx.db.insert(anyTable).values(insertData).returning();
+            const [result] = await inRlsOrPlainTx(ctx.db, async (tx: any) =>
+                tx.insert(anyTable).values(insertData).returning()
+            );
 
             // Realtime push — { data, total } 형태로 emit
+            // ownerRls 시 해당 사용자 데이터만 push (타 사용자에게 누출 방지)
+            // S5: requireAuth로 확실한 userId 획득 (getUserIdentity null 방지)
             if (useRealtime && enabledMethods.has('list')) {
-                const listResult = await fetchListWithTotal(ctx.db);
+                const currentUserId = user?.id;
+                const listResult = await fetchListWithTotal(ctx.db, undefined, currentUserId);
                 ctx.realtime.emit(`${prefix}.list`, listResult);
             }
 
@@ -386,12 +579,26 @@ export function crud<T extends PgTable>(table: T, options?: CrudOptions<T>) {
     const updateDef = !enabledMethods.has('update') ? undefined : mutation(`${prefix}.update`, {
         public: isPublic,
         handler: async (ctx: any, args: any) => {
-            if (!isPublic) ctx.auth.requireAuth();
+            // ownerRls 테이블은 항상 인증 필수
+            const user = (ownerMeta || !isPublic) ? ctx.auth.requireAuth() : null;
 
             const { id, ...updates } = args;
 
             let updateData = { ...updates };
 
+            // ── ownerRls Layer 1: update 시 userId 변경 차단 + 소유자 검증 ──
+            let updateWhere: SQL = eq(pk, id);
+            if (ownerMeta && user) {
+                // WHERE id = ? AND user_id = ? (타인 데이터 수정 불가)
+                updateWhere = and(eq(pk, id), eq(ownerMeta.column, user.id))!;
+                // S1 수정: propertyName(JS명)으로 userId 변경 시도 차단
+                delete updateData[ownerMeta.propertyName];
+                // DB명도 방어적으로 삭제 (만약 클라이언트가 DB명으로 보낸 경우)
+                if (ownerMeta.propertyName !== ownerMeta.columnName) {
+                    delete updateData[ownerMeta.columnName];
+                }
+            }
+
             // updatedAt 자동 갱신
             if (anyTable["updatedAt"]) {
                 updateData.updatedAt = new Date();
@@ -402,15 +609,19 @@ export function crud<T extends PgTable>(table: T, options?: CrudOptions<T>) {
                 updateData = await options.hooks.beforeUpdate(updateData);
             }
 
-            const [result] = await ctx.db.update(anyTable)
-                .set(updateData)
-                .where(eq(pk, id))
-                .returning();
+            const [result] = await inRlsOrPlainTx(ctx.db, async (tx: any) =>
+                tx.update(anyTable)
+                    .set(updateData)
+                    .where(updateWhere)
+                    .returning()
+            );
 
             // Realtime push (list + get 양쪽) — { data, total } 형태
+            // S5: ownerRls 시 user.id 사용 (getUserIdentity null 방지)
             if (useRealtime) {
+                const currentUserId = ownerMeta ? user?.id : undefined;
                 if (enabledMethods.has('list')) {
-                    const listResult = await fetchListWithTotal(ctx.db);
+                    const listResult = await fetchListWithTotal(ctx.db, undefined, currentUserId);
                     ctx.realtime.emit(`${prefix}.list`, listResult);
                 }
                 if (enabledMethods.has('get')) {
@@ -427,20 +638,32 @@ export function crud<T extends PgTable>(table: T, options?: CrudOptions<T>) {
     const removeDef = !enabledMethods.has('remove') ? undefined : mutation(`${prefix}.remove`, {
         public: isPublic,
         handler: async (ctx: any, args: any) => {
-            if (!isPublic) ctx.auth.requireAuth();
-
-            if (options?.softDelete) {
-                const sdField = options.softDelete.field as string;
-                await ctx.db.update(anyTable)
-                    .set({ [sdField]: new Date() } as any)
-                    .where(eq(pk, args.id));
-            } else {
-                await ctx.db.delete(anyTable).where(eq(pk, args.id));
+            // ownerRls 테이블은 항상 인증 필수
+            const user = (ownerMeta || !isPublic) ? ctx.auth.requireAuth() : null;
+
+            // ── ownerRls Layer 1: remove 시 소유자 검증 ──
+            let deleteWhere: SQL = eq(pk, args.id);
+            if (ownerMeta && user) {
+                // WHERE id = ? AND user_id = ? (타인 데이터 삭제 불가)
+                deleteWhere = and(eq(pk, args.id), eq(ownerMeta.column, user.id))!;
             }
 
+            await inRlsOrPlainTx(ctx.db, async (tx: any) => {
+                if (options?.softDelete) {
+                    const sdField = options.softDelete.field as string;
+                    await tx.update(anyTable)
+                        .set({ [sdField]: new Date() } as any)
+                        .where(deleteWhere);
+                } else {
+                    await tx.delete(anyTable).where(deleteWhere);
+                }
+            });
+
             // Realtime push — { data, total } 형태
+            // S5: ownerRls 시 user.id 사용
             if (useRealtime && enabledMethods.has('list')) {
-                const listResult = await fetchListWithTotal(ctx.db);
+                const currentUserId = ownerMeta ? user?.id : undefined;
+                const listResult = await fetchListWithTotal(ctx.db, undefined, currentUserId);
                 ctx.realtime.emit(`${prefix}.list`, listResult);
             }
 

package/src/index.ts

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

package/src/rls-db.ts

@@ -2,12 +2,10 @@ import { sql } from "drizzle-orm";
 import type { PgDatabase } from "drizzle-orm/pg-core";
 
 /**
- * JWT payload.sub(userId)로 RLS 세션 변수를 주입하는 DB 래퍼.
- * Supabase createDrizzle 패턴 참고.
+ * Wraps Drizzle so `transaction()` runs `set_config('app.current_user_id', ...)` first (RLS policies).
+ * Supabase-style session GUC injection.
  *
- * set_config(name, value, is_local=true)
- *   → is_local=true: 현재 트랜잭션에서만 유효
- *   → PgBouncer transaction 모드에서 안전
+ * `set_config(..., true)` is transaction-local (safe with PgBouncer transaction pooling).
  */
 export function createRlsDb(db: PgDatabase<any, any, any>, userId: string) {
     return new Proxy(db, {

package/src/rls.ts

@@ -1,15 +1,99 @@
 import { sql, type SQL } from "drizzle-orm";
-import { pgPolicy, type AnyPgColumn } from "drizzle-orm/pg-core";
+import { pgPolicy, type AnyPgColumn, type PgTable } from "drizzle-orm/pg-core";
 
+// ─── ownerRls 메타데이터 레지스트리 ─────────────────────────
+//
+// getTableConfig()는 pgPolicy 배열을 복사하므로 부착 프로퍼티가 유실됨.
+// 테이블 → 메타데이터 매핑을 WeakMap으로 관리하여 crud()가 접근.
+// WeakMap이므로 테이블이 GC되면 메타데이터도 자동 해제.
+
+export interface OwnerRlsMeta {
+    /** userId 컬럼의 DB 이름 (e.g. "user_id") */
+    columnName: string;
+    /** true면 SELECT에 userId 필터 생략 (누구나 읽기 가능) */
+    readPublic: boolean;
+}
+
+const _ownerRlsRegistry = new WeakMap<PgTable, OwnerRlsMeta>();
+
+/**
+ * 테이블에 등록된 ownerRls 메타데이터를 반환한다.
+ * ownerRls()가 호출되지 않은 테이블은 undefined를 반환.
+ */
+export function getOwnerRlsMeta(table: PgTable): OwnerRlsMeta | undefined {
+    return _ownerRlsRegistry.get(table);
+}
+
+/**
+ * 내부용: ownerRls()가 호출될 때 메타데이터를 레지스트리에 등록.
+ * pgTable의 extraConfig 콜백에서 호출되므로, 테이블 참조가 아닌
+ * 임시 프록시 객체가 전달될 수 있음 → registerOwnerRls()로 사후 등록.
+ */
+export function registerOwnerRls(table: PgTable, meta: OwnerRlsMeta): void {
+    _ownerRlsRegistry.set(table, meta);
+}
+
+// ─── ownerRls — DB-level RLS 정책 선언 + 앱 레벨 메타데이터 등록 ──
+
+/**
+ * 사용자 소유권 기반 RLS 정책을 선언한다.
+ *
+ * 2-Layer 방어:
+ * - Layer 1 (앱 레벨): crud()가 이 메타데이터를 감지하여
+ *   모든 CRUD 쿼리에 WHERE userId = auth.userId 자동 주입.
+ *   PGlite + PostgreSQL 양쪽에서 동작.
+ * - Layer 2 (DB 레벨): PostgreSQL RLS 정책으로 심층 방어.
+ *   createRlsDb()의 transaction() 내에서 set_config 주입.
+ *
+ * @example
+ * ```ts
+ * export const tasks = pgTable("tasks", {
+ *     id: serial("id").primaryKey(),
+ *     title: text("title").notNull(),
+ *     userId: text("user_id").notNull(),
+ * }, (t) => ownerRls(t.userId));
+ *
+ * // read: "public" — 누구나 읽기 가능, CUD는 소유자만
+ * export const posts = pgTable("posts", {
+ *     id: serial("id").primaryKey(),
+ *     content: text("content").notNull(),
+ *     userId: text("user_id").notNull(),
+ * }, (t) => ownerRls(t.userId, { read: "public" }));
+ * ```
+ */
 export function ownerRls(
     userIdColumn: AnyPgColumn,
     options?: { read?: "public" },
 ) {
-    const isOwner = sql`${userIdColumn} = current_setting('app.current_user_id')`;
-    return [
+    // S3 방어: userIdColumn.name 미존재 시 명확한 에러
+    const colName = (userIdColumn as any).name;
+    if (!colName) {
+        throw new Error(
+            "[ownerRls] userIdColumn must have a .name property. " +
+            "Ensure you pass a valid Drizzle column reference (e.g. t.userId)."
+        );
+    }
+
+    /** `missing_ok` avoids errors before first `set_config` and matches PG custom GUC behavior in PGlite. */
+    const isOwner = sql`${userIdColumn} = current_setting('app.current_user_id', true)`;
+
+    // ── 앱 레벨 메타데이터: crud()가 런타임에 읽음 ──
+    const meta: OwnerRlsMeta = {
+        columnName: colName,
+        readPublic: options?.read === "public",
+    };
+
+    const policies = [
         pgPolicy("rls-select", { for: "select", using: options?.read === "public" ? sql`true` : isOwner }),
         pgPolicy("rls-insert", { for: "insert", withCheck: isOwner }),
         pgPolicy("rls-update", { for: "update", using: isOwner, withCheck: isOwner }),
         pgPolicy("rls-delete", { for: "delete", using: isOwner }),
     ];
+
+    // N2 정리: non-enumerable _ownerRlsMeta 마커 제거 (dead code).
+    // ownerRls()는 pgTable extraConfig 콜백에서 호출되며, 이 시점에서는
+    // 테이블 참조가 프록시이므로 WeakMap 등록 불가능.
+    // 실제 메타데이터 등록은 crud()의 detectOwnerMeta() fallback에서 수행.
+
+    return policies;
 }

package/src/server.ts

@@ -7,5 +7,6 @@
  */
 export { createDb } from "./db";
 export { createStorage, storageRoutes } from "./storage";
+export type { StorageImageTierConfig } from "./storage";
 export { createScheduler, getSchedulerInfo } from "./scheduler";
 export { authMiddleware, authRoutes, getUsers } from "./auth";