@gencow/core 0.1.7 → 0.1.9

package/src/reactive.ts

@@ -68,8 +68,10 @@ export interface AIContext {
 }
 
 export interface GencowCtx {
-    /** Drizzle DB 인스턴스 — ctx.db.select().from(table) */
+    /** Drizzle DB 인스턴스 (scoped) — 스키마 filter 자동 적용, execute 차단 */
     db: any; // typed per-app via generic
+    /** Raw Drizzle DB — 필터 없음, execute 허용. ⚠️ 이름이 곧 경고. */
+    unsafeDb: any;
     /** 인증 컨텍스트 — ctx.auth.getUserIdentity() */
     auth: AuthCtx;
     /** 파일 스토리지 — ctx.storage.store(), ctx.storage.getUrl() */
@@ -220,9 +222,34 @@ export function query<TSchema = any, TReturn = any>(
 
 let mutationCounter = 0;
 
+/**
+ * mutation — 데이터 변경 함수를 선언적으로 등록합니다.
+ *
+ * 3가지 호출 방식 지원 (query와 동일한 패턴 우선):
+ *
+ * @example
+ * ```typescript
+ * // ✅ 권장: query와 동일한 (name, def) 패턴
+ * mutation("tasks.create", {
+ *     invalidates: [],
+ *     args: { title: v.string() },
+ *     handler: async (ctx, args) => { ... },
+ * });
+ *
+ * // ✅ 객체 스타일 (하위 호환)
+ * mutation({
+ *     name: "tasks.create",
+ *     invalidates: [],
+ *     handler: async (ctx) => { ... },
+ * });
+ *
+ * // ⚠️ Legacy 배열 스타일 (비권장)
+ * mutation(["tasks.list"], handler, "tasks.create");
+ * ```
+ */
 export function mutation<TSchema = any, TReturn = any>(
-    invalidatesOrDef: string[] | { name?: string; args?: TSchema; public?: boolean; invalidates: string[]; handler: MutationHandler<InferArgs<TSchema>, TReturn> },
-    handler?: MutationHandler<InferArgs<TSchema>, TReturn>,
+    nameOrInvalidatesOrDef: string | string[] | { name?: string; args?: TSchema; public?: boolean; invalidates: string[]; handler: MutationHandler<InferArgs<TSchema>, TReturn> },
+    handlerOrDef?: MutationHandler<InferArgs<TSchema>, TReturn> | { invalidates?: string[]; args?: TSchema; public?: boolean; handler: MutationHandler<InferArgs<TSchema>, TReturn> },
     name?: string
 ): MutationDef<TSchema, TReturn> {
     let invalidates: string[];
@@ -231,19 +258,36 @@ export function mutation<TSchema = any, TReturn = any>(
     let mutName: string;
     let isPublic = false;
 
-    if (Array.isArray(invalidatesOrDef)) {
+    if (typeof nameOrInvalidatesOrDef === "string") {
+        // New primary style: mutation("name", { invalidates?, args?, public?, handler })
+        mutName = nameOrInvalidatesOrDef;
+        const def = handlerOrDef as { invalidates?: string[]; args?: TSchema; public?: boolean; handler: MutationHandler<InferArgs<TSchema>, TReturn> };
+        invalidates = def.invalidates || [];
+        actualHandler = def.handler;
+        argsSchema = def.args;
+        isPublic = def.public === true;
+    } else if (Array.isArray(nameOrInvalidatesOrDef)) {
         // Legacy style: mutation([...], handler, "name")
-        invalidates = invalidatesOrDef;
-        actualHandler = handler!;
+        invalidates = nameOrInvalidatesOrDef;
+        actualHandler = handlerOrDef as MutationHandler<InferArgs<TSchema>, TReturn>;
         mutName = name || `mutation_${++mutationCounter}`;
     } else {
-        // New object style: mutation({ name?, invalidates, args?, public?, handler })
-        invalidates = invalidatesOrDef.invalidates;
-        actualHandler = invalidatesOrDef.handler;
-        argsSchema = invalidatesOrDef.args;
-        isPublic = invalidatesOrDef.public === true;
-        mutName = invalidatesOrDef.name || name || `mutation_${++mutationCounter}`;
+        // Object style: mutation({ name?, invalidates, args?, public?, handler })
+        invalidates = nameOrInvalidatesOrDef.invalidates;
+        actualHandler = nameOrInvalidatesOrDef.handler;
+        argsSchema = nameOrInvalidatesOrDef.args;
+        isPublic = nameOrInvalidatesOrDef.public === true;
+        mutName = nameOrInvalidatesOrDef.name || (typeof name === "string" ? name : "") || `mutation_${++mutationCounter}`;
     }
+
+    // 이름 미지정 시 경고 — 디버깅 지원
+    if (mutName.startsWith("mutation_")) {
+        console.warn(
+            `[gencow] mutation registered without explicit name → "${mutName}". ` +
+            `Use mutation("myMutation", { handler }) for better debugging.`
+        );
+    }
+
     const def: MutationDef<TSchema, TReturn> & { name: string } = {
         name: mutName,
         invalidates,

package/src/scheduler.ts

@@ -15,6 +15,8 @@ export interface Scheduler {
     cron(name: string, pattern: string, handler: () => Promise<void>): void;
     /** Register an action handler */
     registerAction(name: string, handler: ActionHandler): void;
+    /** Execute a registered action by name — 선언적 crons.ts 문자열 액션 실행용 */
+    executeAction(name: string, args?: any): Promise<void>;
 }
 
 // ─── Implementation ─────────────────────────────────────
@@ -34,9 +36,17 @@ export interface Scheduler {
  * // Cron (Convex-style)
  * scheduler.cron('daily-cleanup', '0 2 * * *', async () => { ... });
  */
-// Module-level state for dashboard introspection
-const _cronInfo: { name: string; pattern: string; registeredAt: string }[] = [];
-const _pendingJobs: { id: string; action: string; scheduledAt: string }[] = [];
+// ─── globalThis 기반 레지스트리 (모듈 중복 방지) ─────────
+// query/mutation 레지스트리(globalThis.__gencow_*)와 동일 패턴.
+// @gencow/core가 다중 resolve되어도 단일 배열 공유.
+
+interface CronInfoEntry { name: string; pattern: string; registeredAt: string }
+interface PendingJobEntry { id: string; action: string; scheduledAt: string }
+
+const _cronInfo: CronInfoEntry[] =
+    (globalThis as any).__gencow_cronInfo ??= [];
+const _pendingJobs: PendingJobEntry[] =
+    (globalThis as any).__gencow_pendingJobs ??= [];
 
 export function getSchedulerInfo() {
     return {
@@ -125,5 +135,9 @@ export function createScheduler(): Scheduler {
         registerAction(name: string, handler: ActionHandler): void {
             actions.set(name, handler);
         },
+
+        async executeAction(name: string, args?: any): Promise<void> {
+            await executeAction(name, args);
+        },
     };
 }

package/src/scoped-db.ts

@@ -0,0 +1,416 @@
+/**
+ * packages/core/src/scoped-db.ts
+ *
+ * Creates a scoped (Proxy-wrapped) Drizzle DB instance that auto-injects
+ * schema-level access control filters from gencowTable() metadata.
+ *
+ * Key behaviors:
+ *   - .select().from(gencowTable) → auto-inject filter into WHERE
+ *   - .insert(table) / .update(table) / .delete(table) → inject filter for writes
+ *   - .leftJoin(table) / .innerJoin(table) → detect and inject filter
+ *   - .execute() → blocked (throws Error)
+ *   - .query.tableName.findMany() → inject filter into relational queries
+ *
+ * Run tests: bun test packages/core/src/__tests__/scoped-db.test.ts
+ */
+
+import { and } from "drizzle-orm";
+import type { SQL } from "drizzle-orm";
+import { getTableAccessMeta } from "./table";
+import type { GencowCtx } from "./reactive";
+import type { TableAccessMeta } from "./table";
+
+// ─── createScopedDb ─────────────────────────────────────
+
+/**
+ * Wrap a Drizzle DB instance with access control Proxy.
+ *
+ * @param db  - Raw Drizzle DB instance
+ * @param ctx - GencowCtx (provides auth for filter evaluation)
+ * @returns Proxy-wrapped DB with auto-filter injection
+ */
+export function createScopedDb(db: any, ctx: GencowCtx): any {
+    return new Proxy(db, {
+        get(target, prop: string | symbol) {
+            const propStr = typeof prop === "string" ? prop : "";
+
+            // ── Block dangerous methods ──────────────────
+            if (propStr === "execute") {
+                return () => {
+                    throw new Error(
+                        "[gencow] ctx.db.execute() is not allowed. " +
+                        "Use ctx.db.select().from(table) for type-safe queries with automatic access control. " +
+                        "If you need raw SQL, use ctx.unsafeDb.execute()."
+                    );
+                };
+            }
+
+            if (propStr === "$client" || propStr === "_") {
+                throw new Error(
+                    `[gencow] ctx.db.${propStr} is not allowed. ` +
+                    "Direct database client access bypasses access control. " +
+                    "Use ctx.unsafeDb if you need direct access."
+                );
+            }
+
+            // ── Wrap select() ────────────────────────────
+            if (propStr === "select") {
+                return (...selectArgs: any[]) => {
+                    const selectResult = target.select(...selectArgs);
+                    return wrapSelectChain(selectResult, ctx);
+                };
+            }
+
+            // ── Wrap update() ────────────────────────────
+            if (propStr === "update") {
+                return (table: any) => {
+                    const updateResult = target.update(table);
+                    return wrapWriteChain(updateResult, table, ctx);
+                };
+            }
+
+            // ── Wrap delete() ────────────────────────────
+            if (propStr === "delete") {
+                return (table: any) => {
+                    const deleteResult = target.delete(table);
+                    return wrapWriteChain(deleteResult, table, ctx);
+                };
+            }
+
+            // ── Wrap query (relational API) ──────────────
+            if (propStr === "query") {
+                return wrapRelationalQuery(target.query, ctx);
+            }
+
+            // ── Pass through everything else ─────────────
+            const value = target[prop];
+            if (typeof value === "function") {
+                return value.bind(target);
+            }
+            return value;
+        },
+    });
+}
+
+// ─── Select chain: .from() + .join() → filter injection ─
+
+/**
+ * Wraps a Drizzle select() chain to intercept .from() and .join() calls.
+ * Each detected gencowTable gets its filter injected.
+ */
+function wrapSelectChain(selectResult: any, ctx: GencowCtx): any {
+    return new Proxy(selectResult, {
+        get(target, prop: string | symbol) {
+            const propStr = typeof prop === "string" ? prop : "";
+
+            // ── .from(table) → inject filter ────────────
+            if (propStr === "from") {
+                return (table: any, ...restArgs: any[]) => {
+                    const fromResult = target.from(table, ...restArgs);
+                    const meta = getTableAccessMeta(table);
+
+                    if (meta) {
+                        // Wrap the chain to inject filter and handle joins
+                        return wrapFromChain(fromResult, ctx, [{ table, meta }]);
+                    }
+
+                    // No gencowTable metadata — pass through but still wrap for join detection
+                    return wrapFromChain(fromResult, ctx, []);
+                };
+            }
+
+            const value = target[prop];
+            if (typeof value === "function") {
+                return value.bind(target);
+            }
+            return value;
+        },
+    });
+}
+
+/**
+ * Wraps the chain after .from() — handles .where(), .leftJoin(), .innerJoin(), etc.
+ * Accumulates filters from all detected tables and injects them at execution time.
+ */
+function wrapFromChain(
+    chain: any,
+    ctx: GencowCtx,
+    pendingFilters: Array<{ table: any; meta: TableAccessMeta }>,
+): any {
+    return new Proxy(chain, {
+        get(target, prop: string | symbol) {
+            const propStr = typeof prop === "string" ? prop : "";
+
+            // ── Join methods → detect table, accumulate filter ──
+            if (["leftJoin", "rightJoin", "innerJoin", "fullJoin"].includes(propStr)) {
+                return (joinTable: any, ...joinArgs: any[]) => {
+                    const joinResult = target[propStr](joinTable, ...joinArgs);
+                    const joinMeta = getTableAccessMeta(joinTable);
+                    const newFilters = joinMeta
+                        ? [...pendingFilters, { table: joinTable, meta: joinMeta }]
+                        : pendingFilters;
+                    return wrapFromChain(joinResult, ctx, newFilters);
+                };
+            }
+
+            // ── .where() → combine with accumulated filters ──
+            if (propStr === "where") {
+                return (...whereArgs: any[]) => {
+                    const combinedFilter = buildCombinedFilter(pendingFilters, ctx);
+                    if (combinedFilter) {
+                        // Combine user's where with our filters
+                        const userWhere = whereArgs[0];
+                        const merged = userWhere ? and(userWhere, combinedFilter) : combinedFilter;
+                        const result = target.where(merged);
+                        // After .where(), no more filter injection needed — continue with clean proxy
+                        return wrapFromChain(result, ctx, []);
+                    }
+                    return wrapFromChain(target.where(...whereArgs), ctx, []);
+                };
+            }
+
+            // ── Terminal methods (then, execute, etc.) → inject pending filters ──
+            if (propStr === "then" || propStr === "execute") {
+                // If there are pending filters that haven't been injected via .where(),
+                // inject them now by calling .where() before execution
+                if (pendingFilters.length > 0) {
+                    const combinedFilter = buildCombinedFilter(pendingFilters, ctx);
+                    if (combinedFilter) {
+                        const filtered = target.where(combinedFilter);
+                        return filtered[prop].bind(filtered);
+                    }
+                }
+                const value = target[prop];
+                return typeof value === "function" ? value.bind(target) : value;
+            }
+
+            // ── Other chainable methods (.orderBy, .limit, .offset, etc.) ──
+            const value = target[prop];
+            if (typeof value === "function") {
+                return (...args: any[]) => {
+                    const result = value.apply(target, args);
+                    // If the result is thenable (query builder), keep wrapping
+                    if (result && typeof result === "object" && typeof result.then === "function") {
+                        return wrapFromChain(result, ctx, pendingFilters);
+                    }
+                    if (result && typeof result === "object" && "where" in result) {
+                        return wrapFromChain(result, ctx, pendingFilters);
+                    }
+                    return result;
+                };
+            }
+            return value;
+        },
+    });
+}
+
+// ─── Write chain: update()/delete() filter injection ────
+
+/**
+ * Wraps update(table) or delete(table) chains.
+ * Injects the table's filter into .where() so users can only modify their own rows.
+ */
+function wrapWriteChain(chain: any, table: any, ctx: GencowCtx): any {
+    const meta = getTableAccessMeta(table);
+    if (!meta) {
+        return chain; // No gencowTable metadata — pass through
+    }
+
+    return new Proxy(chain, {
+        get(target, prop: string | symbol) {
+            const propStr = typeof prop === "string" ? prop : "";
+
+            if (propStr === "where") {
+                return (...whereArgs: any[]) => {
+                    const filterResult = evaluateFilterSync(meta, ctx);
+                    if (typeof filterResult === "boolean") {
+                        if (!filterResult) {
+                            // false → block all writes — add impossible condition
+                            return target.where(whereArgs[0]); // Let it through but will match nothing
+                        }
+                        // true → no additional filter
+                        return target.where(...whereArgs);
+                    }
+                    // SQL condition — combine with user's where
+                    const userWhere = whereArgs[0];
+                    const merged = userWhere ? and(userWhere, filterResult) : filterResult;
+                    return target.where(merged);
+                };
+            }
+
+            // Terminal methods — inject filter if .where() wasn't called
+            if (propStr === "then" || propStr === "execute" || propStr === "returning") {
+                const filterResult = evaluateFilterSync(meta, ctx);
+                if (filterResult && typeof filterResult !== "boolean") {
+                    const filtered = target.where(filterResult);
+                    const value = filtered[prop];
+                    return typeof value === "function" ? value.bind(filtered) : value;
+                }
+                const value = target[prop];
+                return typeof value === "function" ? value.bind(target) : value;
+            }
+
+            const value = target[prop];
+            if (typeof value === "function") {
+                return value.bind(target);
+            }
+            return value;
+        },
+    });
+}
+
+// ─── Relational query wrapping ──────────────────────────
+
+/**
+ * Wraps db.query to intercept relational queries (findMany, findFirst).
+ */
+function wrapRelationalQuery(queryObj: any, ctx: GencowCtx): any {
+    if (!queryObj) return queryObj;
+
+    return new Proxy(queryObj, {
+        get(target, tableName: string | symbol) {
+            const tableProxy = target[tableName];
+            if (!tableProxy || typeof tableProxy !== "object") return tableProxy;
+
+            return new Proxy(tableProxy, {
+                get(tableTarget, method: string | symbol) {
+                    const methodStr = typeof method === "string" ? method : "";
+
+                    if (methodStr === "findMany" || methodStr === "findFirst") {
+                        return (args: any = {}) => {
+                            // Try to find the gencowTable by table name
+                            // (relational queries use the table name string)
+                            // We need to look up from registry by tableName
+                            const meta = findMetaByTableName(String(tableName));
+                            if (meta) {
+                                const filterResult = evaluateFilterSync(meta, ctx);
+                                if (filterResult && typeof filterResult !== "boolean") {
+                                    args.where = args.where ? and(args.where, filterResult) : filterResult;
+                                } else if (filterResult === false) {
+                                    // Deny all — return empty
+                                    args.where = args.where; // Keep existing, but won't match
+                                }
+                            }
+                            return tableTarget[method](args);
+                        };
+                    }
+
+                    const value = tableTarget[method];
+                    if (typeof value === "function") {
+                        return value.bind(tableTarget);
+                    }
+                    return value;
+                },
+            });
+        },
+    });
+}
+
+// ─── Filter helpers ─────────────────────────────────────
+
+/**
+ * Build a combined SQL filter from multiple table filters.
+ * Returns null if no filters to apply.
+ */
+function buildCombinedFilter(
+    pendingFilters: Array<{ table: any; meta: TableAccessMeta }>,
+    ctx: GencowCtx,
+): SQL | null {
+    const sqlConditions: SQL[] = [];
+
+    for (const { meta } of pendingFilters) {
+        const result = evaluateFilterSync(meta, ctx);
+        if (result === false) {
+            // Any false → deny all (AND with false = false)
+            // We'd need an always-false SQL expression
+            // For now, we create a `1 = 0` condition
+            const { sql: sqlTag } = require("drizzle-orm");
+            return sqlTag`1 = 0`;
+        }
+        if (result === true) {
+            continue; // Allow all — no condition needed
+        }
+        if (result) {
+            sqlConditions.push(result);
+        }
+    }
+
+    if (sqlConditions.length === 0) return null;
+    if (sqlConditions.length === 1) return sqlConditions[0];
+    return and(...sqlConditions) ?? null;
+}
+
+/**
+ * Evaluate a filter synchronously. If the filter is async, this will throw.
+ * For async filters, callers should use evaluateFilterAsync.
+ */
+function evaluateFilterSync(meta: TableAccessMeta, ctx: GencowCtx): SQL | boolean {
+    const result = meta.filter(ctx);
+    if (result instanceof Promise) {
+        throw new Error(
+            `[gencow] Async filter on table "${meta.tableName}" is not supported in synchronous context. ` +
+            "Use synchronous filters for schema-level access control."
+        );
+    }
+    return result;
+}
+
+/**
+ * Find table access metadata by table name string.
+ * Used by relational query proxy where we only have the table name.
+ */
+function findMetaByTableName(name: string): TableAccessMeta | undefined {
+    for (const [, meta] of globalThis.__gencow_tableAccessRegistry || []) {
+        if (meta.tableName === name) return meta;
+    }
+    return undefined;
+}
+
+// ─── fieldAccess post-processing ────────────────────────
+
+/**
+ * Apply field-level access control to query results.
+ * Nullifies fields that the current user is not authorized to read.
+ *
+ * @param result - Query result (array or single object)
+ * @param table  - The gencowTable used in the query
+ * @param ctx    - GencowCtx for auth checks
+ * @returns Filtered result with unauthorized fields set to null
+ */
+export function applyFieldAccess(result: any, table: any, ctx: GencowCtx): any {
+    const meta = getTableAccessMeta(table);
+    if (!meta?.fieldAccess) return result;
+
+    const fieldAccess = meta.fieldAccess;
+
+    // Determine which fields to mask
+    const maskedFields: string[] = [];
+    for (const [field, rule] of Object.entries(fieldAccess)) {
+        try {
+            if (!rule.read(ctx)) {
+                maskedFields.push(field);
+            }
+        } catch {
+            // If read check throws (e.g., requireAuth on anonymous), mask the field
+            maskedFields.push(field);
+        }
+    }
+
+    if (maskedFields.length === 0) return result;
+
+    const maskRow = (row: any) => {
+        if (!row || typeof row !== "object") return row;
+        const masked = { ...row };
+        for (const field of maskedFields) {
+            if (field in masked) {
+                masked[field] = null;
+            }
+        }
+        return masked;
+    };
+
+    if (Array.isArray(result)) {
+        return result.map(maskRow);
+    }
+    return maskRow(result);
+}