@opensaas/stack-core 0.24.0 → 0.25.0

package/tests/context.test.ts

@@ -1,5 +1,7 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
 import { getContext } from '../src/context/index.js'
+import { defineFragment } from '../src/query/index.js'
+import { virtual } from '../src/fields/index.js'
 import type { OpenSaasConfig } from '../src/config/types.js'
 
 describe('getContext', () => {
@@ -212,6 +214,131 @@ describe('getContext', () => {
       expect(result).toEqual(mockUser)
     })
 
+    describe('findUnique unique-where enforcement (#567)', () => {
+      it('accepts a valid unique where (id) and keeps access + include intact', async () => {
+        const mockUser = { id: '1', name: 'John', email: 'john@example.com' }
+        mockPrisma.user.findFirst.mockResolvedValue(mockUser)
+
+        const context = await getContext(config, mockPrisma, null)
+        const result = await context.db.user.findUnique({
+          where: { id: '1' },
+          include: { posts: true },
+        })
+
+        // Access control still runs and the underlying delegate is invoked with
+        // the merged where + include (proving access + include path is intact).
+        expect(mockPrisma.user.findFirst).toHaveBeenCalledWith(
+          expect.objectContaining({
+            where: expect.objectContaining({ id: '1' }),
+            include: { posts: true },
+          }),
+        )
+        expect(result).toEqual(mockUser)
+      })
+
+      it('accepts a configured-unique field (email) as the unique where', async () => {
+        const mockUser = { id: '1', name: 'John', email: 'john@example.com' }
+        mockPrisma.user.findFirst.mockResolvedValue(mockUser)
+
+        const context = await getContext(config, mockPrisma, null)
+        const result = await context.db.user.findUnique({
+          where: { email: 'john@example.com' },
+        })
+
+        expect(mockPrisma.user.findFirst).toHaveBeenCalled()
+        expect(result).toEqual(mockUser)
+      })
+
+      it('narrows the result through a query fragment with a unique where', async () => {
+        const mockUser = { id: '1', name: 'John', email: 'john@example.com' }
+        mockPrisma.user.findFirst.mockResolvedValue(mockUser)
+
+        const fragment = defineFragment<{ id: string; name: string; email: string }>()({
+          id: true,
+          name: true,
+        } as const)
+
+        const context = await getContext(config, mockPrisma, null)
+        const result = await context.db.user.findUnique({ where: { id: '1' }, query: fragment })
+
+        // Fragment narrows the result to only the requested fields (email omitted)
+        expect(result).toEqual({ id: '1', name: 'John' })
+      })
+
+      it('THROWS on a non-unique where (caller-shape error, not a silent null)', async () => {
+        mockPrisma.user.findFirst.mockResolvedValue({ id: '1', name: 'John' })
+
+        const context = await getContext(config, mockPrisma, null)
+
+        // `name` is not a unique key — this is misuse and must throw, not return null.
+        await expect(context.db.user.findUnique({ where: { name: 'John' } })).rejects.toThrow(
+          /requires a unique `where`/,
+        )
+        // The error guides the caller toward findFirst (the non-unique escape hatch).
+        await expect(context.db.user.findUnique({ where: { name: 'John' } })).rejects.toThrow(
+          /findFirst/,
+        )
+        // Guard runs before any DB access.
+        expect(mockPrisma.user.findFirst).not.toHaveBeenCalled()
+      })
+
+      it('THROWS when a unique key is mixed with extra non-unique keys', async () => {
+        const context = await getContext(config, mockPrisma, null)
+
+        await expect(
+          context.db.user.findUnique({ where: { id: '1', name: 'John' } }),
+        ).rejects.toThrow(/requires a unique `where`/)
+        expect(mockPrisma.user.findFirst).not.toHaveBeenCalled()
+      })
+
+      it('THROWS on an empty where', async () => {
+        const context = await getContext(config, mockPrisma, null)
+
+        await expect(context.db.user.findUnique({ where: {} })).rejects.toThrow(
+          /requires a unique `where`/,
+        )
+        expect(mockPrisma.user.findFirst).not.toHaveBeenCalled()
+      })
+
+      it('returns null on access denial (silent-failure contract preserved)', async () => {
+        const deniedConfig: OpenSaasConfig = {
+          ...config,
+          lists: {
+            ...config.lists,
+            User: {
+              ...config.lists.User,
+              access: {
+                operation: {
+                  query: () => false,
+                  create: () => true,
+                  update: () => true,
+                  delete: () => true,
+                },
+              },
+            },
+          },
+        }
+        mockPrisma.user.findFirst.mockResolvedValue({ id: '1', name: 'John' })
+
+        const context = await getContext(deniedConfig, mockPrisma, null)
+        const result = await context.db.user.findUnique({ where: { id: '1' } })
+
+        // Access denied -> null (not a throw), and the DB is never queried.
+        expect(result).toBeNull()
+        expect(mockPrisma.user.findFirst).not.toHaveBeenCalled()
+      })
+
+      it('returns null when no record matches a valid unique where', async () => {
+        mockPrisma.user.findFirst.mockResolvedValue(null)
+
+        const context = await getContext(config, mockPrisma, null)
+        const result = await context.db.user.findUnique({ where: { id: 'missing' } })
+
+        expect(result).toBeNull()
+        expect(mockPrisma.user.findFirst).toHaveBeenCalled()
+      })
+    })
+
     it('should delegate findMany to prisma with access control', async () => {
       const mockUsers = [
         { id: '1', name: 'John' },
@@ -226,6 +353,360 @@ describe('getContext', () => {
       expect(result).toEqual(mockUsers)
     })
 
+    describe('findFirst', () => {
+      it('should return the first matching row', async () => {
+        const mockUsers = [
+          { id: '1', name: 'John', email: 'john@example.com' },
+          { id: '2', name: 'Jane', email: 'jane@example.com' },
+        ]
+        mockPrisma.user.findMany.mockResolvedValue(mockUsers)
+
+        const context = await getContext(config, mockPrisma, null)
+        const result = await context.db.user.findFirst()
+
+        // Delegates to the access-controlled findMany with take: 1
+        expect(mockPrisma.user.findMany).toHaveBeenCalledWith(expect.objectContaining({ take: 1 }))
+        expect(result).toEqual(mockUsers[0])
+      })
+
+      it('should return null (not undefined, not throw) when nothing matches', async () => {
+        mockPrisma.user.findMany.mockResolvedValue([])
+
+        const context = await getContext(config, mockPrisma, null)
+        const result = await context.db.user.findFirst({ where: { name: 'Nobody' } })
+
+        expect(result).toBeNull()
+        expect(result).not.toBeUndefined()
+      })
+
+      it('should respect where and orderBy', async () => {
+        const mockUser = { id: '2', name: 'Jane', email: 'jane@example.com' }
+        mockPrisma.user.findMany.mockResolvedValue([mockUser])
+
+        const context = await getContext(config, mockPrisma, null)
+        const result = await context.db.user.findFirst({
+          where: { name: 'Jane' },
+          orderBy: { name: 'asc' },
+        })
+
+        expect(mockPrisma.user.findMany).toHaveBeenCalledWith(
+          expect.objectContaining({
+            where: expect.objectContaining({ name: 'Jane' }),
+            orderBy: { name: 'asc' },
+            take: 1,
+          }),
+        )
+        expect(result).toEqual(mockUser)
+      })
+
+      it('should honour query-access denial the same as findMany (denied -> null)', async () => {
+        const deniedConfig: OpenSaasConfig = {
+          ...config,
+          lists: {
+            ...config.lists,
+            User: {
+              ...config.lists.User,
+              access: {
+                operation: {
+                  query: () => false,
+                  create: () => true,
+                  update: () => true,
+                  delete: () => true,
+                },
+              },
+            },
+          },
+        }
+        mockPrisma.user.findMany.mockResolvedValue([
+          { id: '1', name: 'John', email: 'john@example.com' },
+        ])
+
+        const context = await getContext(deniedConfig, mockPrisma, null)
+        const result = await context.db.user.findFirst()
+
+        // Denied query short-circuits before hitting prisma — exactly like findMany
+        expect(result).toBeNull()
+        expect(mockPrisma.user.findMany).not.toHaveBeenCalled()
+      })
+
+      it('should respect a query fragment, narrowing the returned single result', async () => {
+        const mockUsers = [
+          { id: '1', name: 'John', email: 'john@example.com' },
+          { id: '2', name: 'Jane', email: 'jane@example.com' },
+        ]
+        mockPrisma.user.findMany.mockResolvedValue(mockUsers)
+
+        const fragment = defineFragment<{ id: string; name: string; email: string }>()({
+          id: true,
+          name: true,
+        } as const)
+
+        const context = await getContext(config, mockPrisma, null)
+        const result = await context.db.user.findFirst({ query: fragment })
+
+        // Fragment narrows the result to only the requested fields (email omitted)
+        expect(result).toEqual({ id: '1', name: 'John' })
+      })
+    })
+
+    describe('explicit include merges with access control (#566)', () => {
+      // Author has many Posts; Post.query access scopes to published posts only.
+      // A caller-supplied `include` must NOT bypass that per-relation filter.
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      let relPrisma: any
+      let relConfig: OpenSaasConfig
+
+      beforeEach(() => {
+        relPrisma = {
+          author: {
+            findFirst: vi.fn(),
+            findUnique: vi.fn(),
+            findMany: vi.fn(),
+          },
+          post: {
+            findFirst: vi.fn(),
+            findUnique: vi.fn(),
+            findMany: vi.fn(),
+          },
+          comment: {
+            findFirst: vi.fn(),
+            findMany: vi.fn(),
+          },
+        }
+
+        relConfig = {
+          db: { provider: 'postgresql', url: 'postgresql://localhost:5432/test' },
+          lists: {
+            Author: {
+              fields: {
+                name: { type: 'text' },
+                posts: { type: 'relationship', ref: 'Post.author', many: true },
+              },
+              access: { operation: { query: () => true } },
+            },
+            Post: {
+              fields: {
+                title: { type: 'text' },
+                author: { type: 'relationship', ref: 'Author.posts' },
+                comments: { type: 'relationship', ref: 'Comment.post', many: true },
+              },
+              access: {
+                // Row filter: only published posts are visible.
+                operation: { query: () => ({ status: { equals: 'published' } }) },
+              },
+            },
+            Comment: {
+              fields: {
+                body: { type: 'text' },
+                post: { type: 'relationship', ref: 'Post.comments' },
+              },
+              access: {
+                operation: { query: () => ({ approved: { equals: true } }) },
+              },
+            },
+            Secret: {
+              fields: {
+                value: { type: 'text' },
+              },
+              // Fully denied list.
+              access: { operation: { query: () => false } },
+            },
+          },
+        }
+        // Add a denied relation onto Author for the "drop denied relation" test.
+        relConfig.lists.Author.fields.secrets = {
+          type: 'relationship',
+          ref: 'Secret',
+          many: true,
+        }
+      })
+
+      it('findMany: caller include {posts:true} applies the relation access where (not bare true)', async () => {
+        relPrisma.author.findMany.mockResolvedValue([{ id: 'a1', name: 'Jo', posts: [] }])
+
+        const context = await getContext(relConfig, relPrisma, null)
+        await context.db.author.findMany({ include: { posts: true } })
+
+        // The relation is fetched WITH the Post query-access where (NOT bare true),
+        // proving the row-level bypass is closed.
+        const call = relPrisma.author.findMany.mock.calls[0][0]
+        expect(call.include.posts).not.toBe(true)
+        expect(call.include.posts.where).toEqual({ status: { equals: 'published' } })
+      })
+
+      it('findUnique: caller include {posts:true} applies the relation access where', async () => {
+        relPrisma.author.findFirst.mockResolvedValue({ id: 'a1', name: 'Jo', posts: [] })
+
+        const context = await getContext(relConfig, relPrisma, null)
+        await context.db.author.findUnique({ where: { id: 'a1' }, include: { posts: true } })
+
+        const call = relPrisma.author.findFirst.mock.calls[0][0]
+        expect(call.where).toEqual(expect.objectContaining({ id: 'a1' }))
+        expect(call.include.posts).not.toBe(true)
+        expect(call.include.posts.where).toEqual({ status: { equals: 'published' } })
+      })
+
+      it('drops a relation whose query access is false when named in the caller include', async () => {
+        relPrisma.author.findMany.mockResolvedValue([{ id: 'a1', name: 'Jo' }])
+
+        const context = await getContext(relConfig, relPrisma, null)
+        await context.db.author.findMany({ include: { secrets: true, posts: true } })
+
+        const call = relPrisma.author.findMany.mock.calls[0][0]
+        // Denied `secrets` relation is dropped; allowed `posts` keeps its filter.
+        expect(call.include.secrets).toBeUndefined()
+        expect(call.include.posts.where).toEqual({ status: { equals: 'published' } })
+      })
+
+      it('AND-combines a caller nested where with the relation access where', async () => {
+        relPrisma.author.findMany.mockResolvedValue([{ id: 'a1', name: 'Jo', posts: [] }])
+
+        const context = await getContext(relConfig, relPrisma, null)
+        await context.db.author.findMany({
+          include: { posts: { where: { title: { contains: 'hello' } } } },
+        })
+
+        const call = relPrisma.author.findMany.mock.calls[0][0]
+        // Both the access where and the caller where are applied via AND.
+        expect(call.include.posts.where).toEqual({
+          AND: [{ status: { equals: 'published' } }, { title: { contains: 'hello' } }],
+        })
+      })
+
+      it('access-filters nested (2-level) caller includes at every level', async () => {
+        relPrisma.author.findMany.mockResolvedValue([{ id: 'a1', name: 'Jo', posts: [] }])
+
+        const context = await getContext(relConfig, relPrisma, null)
+        await context.db.author.findMany({
+          include: { posts: { include: { comments: true } } },
+        })
+
+        const call = relPrisma.author.findMany.mock.calls[0][0]
+        // Level 1 (posts) and level 2 (comments) both carry their access where.
+        expect(call.include.posts.where).toEqual({ status: { equals: 'published' } })
+        expect(call.include.posts.include.comments.where).toEqual({ approved: { equals: true } })
+      })
+
+      it('sudo with explicit include returns the include unfiltered (behaviour preserved)', async () => {
+        relPrisma.author.findMany.mockResolvedValue([{ id: 'a1', name: 'Jo' }])
+
+        const context = await getContext(relConfig, relPrisma, null).sudo()
+        await context.db.author.findMany({ include: { posts: true, secrets: true } })
+
+        // Under sudo the caller include is used as-is: no filter, nothing dropped.
+        expect(relPrisma.author.findMany).toHaveBeenCalledWith(
+          expect.objectContaining({ include: { posts: true, secrets: true } }),
+        )
+      })
+
+      it('query fragment path is unaffected by the merge (fragment include used, unfiltered)', async () => {
+        relPrisma.author.findMany.mockResolvedValue([{ id: 'a1', name: 'Jo', posts: [] }])
+
+        const postsFragment = defineFragment<{ id: string; title: string }>()({
+          title: true,
+        } as const)
+        const fragment = defineFragment<{ id: string; name: string; posts: unknown }>()({
+          id: true,
+          name: true,
+          posts: postsFragment,
+        } as const)
+
+        const context = await getContext(relConfig, relPrisma, null)
+        await context.db.author.findMany({ query: fragment })
+
+        const call = relPrisma.author.findMany.mock.calls[0][0]
+        // Fragment-built include is used as-is; the merge helper is NOT applied to
+        // the fragment path, so the relation carries no access `where` here. (The
+        // fragment posts-selection contains only scalars, so it builds to `true`.)
+        expect(call.include).toEqual({ posts: true })
+      })
+
+      // Regression: when buildIncludeWithAccessControl returns `undefined` (a
+      // NON-denial outcome), the caller include must PASS THROUGH unchanged
+      // rather than every declared relation being silently dropped. The original
+      // #566 merge treated `undefined` as "all relations denied" (fail-closed
+      // data loss). `undefined` is returned in three non-denial cases:
+      //   1. inside a resolveOutput hook / virtual-field context,
+      //   2. at MAX_DEPTH,
+      //   3. when a list has no relationships.
+      describe('passes caller include through when no access include is computed', () => {
+        // Build an Author config with a virtual field whose resolveOutput issues a
+        // read WITH an explicit include. While that hook runs,
+        // _resolveOutputCounter.depth > 0, so buildIncludeWithAccessControl
+        // returns undefined for the inner read — exercising the
+        // `accessControlledInclude === undefined` passthrough path.
+        function configWithResolveOutputProbe(
+          callerInclude: Record<string, unknown>,
+          capture: (include: unknown) => void,
+        ): OpenSaasConfig {
+          return {
+            ...relConfig,
+            lists: {
+              ...relConfig.lists,
+              Author: {
+                ...relConfig.lists.Author,
+                fields: {
+                  ...relConfig.lists.Author.fields,
+                  commentSummary: virtual({
+                    type: 'string',
+                    hooks: {
+                      resolveOutput: async ({ context }) => {
+                        await context.db.comment.findMany({ include: callerInclude })
+                        capture(relPrisma.comment.findMany.mock.calls[0][0].include)
+                        return 'summary'
+                      },
+                    },
+                  }),
+                },
+              },
+            },
+          }
+        }
+
+        it('findUnique inside a resolveOutput hook keeps the caller include (not dropped)', async () => {
+          let innerIncludeSeen: unknown
+          const hookConfig = configWithResolveOutputProbe({ post: true }, (include) => {
+            innerIncludeSeen = include
+          })
+
+          relPrisma.author.findFirst.mockResolvedValue({ id: 'a1', name: 'Jo' })
+          relPrisma.comment.findMany.mockResolvedValue([{ id: 'c1', body: 'hi', post: null }])
+
+          const context = await getContext(hookConfig, relPrisma, null)
+          await context.db.author.findUnique({ where: { id: 'a1' } })
+
+          // The caller include `{ post: true }` survives: the declared `post`
+          // relation is NOT dropped despite the access include being undefined here.
+          expect(innerIncludeSeen).toEqual({ post: true })
+        })
+
+        it('findMany inside a resolveOutput hook passes a NESTED caller include through whole', async () => {
+          let innerIncludeSeen: unknown
+          const hookConfig = configWithResolveOutputProbe(
+            { post: { include: { author: true } } },
+            (include) => {
+              innerIncludeSeen = include
+            },
+          )
+
+          relPrisma.author.findMany.mockResolvedValue([{ id: 'a1', name: 'Jo' }])
+          relPrisma.comment.findMany.mockResolvedValue([{ id: 'c1', body: 'hi', post: null }])
+
+          const context = await getContext(hookConfig, relPrisma, null)
+          await context.db.author.findMany()
+
+          // The whole nested caller include passes through untouched (no access
+          // include exists to merge against in resolveOutput context).
+          expect(innerIncludeSeen).toEqual({ post: { include: { author: true } } })
+        })
+
+        // The MAX_DEPTH and no-relationships cases also make
+        // buildIncludeWithAccessControl return undefined; they flow through the
+        // identical `accessControlledInclude === undefined` branch verified above,
+        // so the resolveOutput probe covers all three non-denial cases.
+      })
+    })
+
     it('should delegate create to prisma with access control and hooks', async () => {
       const mockUser = { id: '1', name: 'John', email: 'john@example.com' }
       mockPrisma.user.create.mockResolvedValue(mockUser)

package/tests/field-types.test.ts

@@ -778,17 +778,31 @@ describe('Field Types', () => {
         const field = json({ validation: { isRequired: true } })
         const schema = field.getZodSchema('metadata', 'create')
 
+        // Any present non-null JSON value is accepted, including falsy values
         expect(schema.safeParse({ key: 'value' }).success).toBe(true)
-        // JSON field with isRequired still accepts undefined due to z.unknown() behavior
-        expect(schema.safeParse(undefined).success).toBe(true)
+        expect(schema.safeParse([1, 2, 3]).success).toBe(true)
+        expect(schema.safeParse(0).success).toBe(true)
+        expect(schema.safeParse('').success).toBe(true)
+        expect(schema.safeParse(false).success).toBe(true)
+        // A required json field must reject undefined on create (issue #597)
+        expect(schema.safeParse(undefined).success).toBe(false)
+        // A required json field means non-null: reject a present null (issue #604)
+        expect(schema.safeParse(null).success).toBe(false)
       })
 
-      test('allows undefined for required field in update mode', () => {
+      test('allows undefined but rejects null for required field in update mode', () => {
         const field = json({ validation: { isRequired: true } })
         const schema = field.getZodSchema('metadata', 'update')
 
         expect(schema.safeParse({ key: 'value' }).success).toBe(true)
+        // Omitted/undefined still passes on update (issue #570)
         expect(schema.safeParse(undefined).success).toBe(true)
+        // Present non-null falsy values pass
+        expect(schema.safeParse(0).success).toBe(true)
+        expect(schema.safeParse('').success).toBe(true)
+        expect(schema.safeParse(false).success).toBe(true)
+        // A present null is rejected — required json means non-null (issue #604)
+        expect(schema.safeParse(null).success).toBe(false)
       })
     })