@opensaas/stack-core 0.27.1 → 0.28.0

package/src/config/plugin-engine.ts

@@ -4,7 +4,6 @@ import type {
   PluginContext,
   ListConfig,
   Hooks,
-  OperationAccess,
   McpCustomTool,
   BaseFieldConfig,
 } from './types.js'
@@ -125,29 +124,6 @@ function mergeHooks(existing: Hooks | undefined, extension: Hooks | undefined):
   return Object.keys(merged).length > 0 ? (merged as Hooks) : undefined
 }
 
-/**
- * Merge access control from extension into existing access
- */
-function mergeAccess(
-  existing: { operation?: OperationAccess } | undefined,
-  extension: { operation?: OperationAccess } | undefined,
-): { operation?: OperationAccess } | undefined {
-  if (!extension) return existing
-  if (!existing) return extension
-
-  const merged: { operation?: OperationAccess } = {}
-
-  // Merge operation access (use extension if provided, otherwise keep existing)
-  if (existing.operation || extension.operation) {
-    merged.operation = {
-      ...existing.operation,
-      ...extension.operation,
-    }
-  }
-
-  return merged
-}
-
 /**
  * Execute plugins and transform config
  * Returns modified config with plugin data attached
@@ -197,6 +173,19 @@ export async function executePlugins(config: OpenSaasConfig): Promise<OpenSaasCo
           )
         }
 
+        // Operation-level access belongs to whoever owns the list (the
+        // application, or an earlier plugin that created it via addList).
+        // An extension of a pre-existing list must never define or override
+        // that access — see ADR-0013. Fields/hooks/relationships/mcp may
+        // still be merged in below.
+        if (extension.access?.operation) {
+          throw new Error(
+            `Plugin "${plugin.name}" tried to set operation-level access while extending list "${name}", ` +
+              `but access control belongs to the application (or whichever party created the list), never a ` +
+              `plugin extending it. Remove "access" from this extension — see ADR-0013.`,
+          )
+        }
+
         // Deep merge fields
         const mergedFields = {
           ...existing.fields,
@@ -206,9 +195,6 @@ export async function executePlugins(config: OpenSaasConfig): Promise<OpenSaasCo
         // Merge hooks
         const mergedHooks = mergeHooks(existing.hooks, extension.hooks)
 
-        // Merge access control
-        const mergedAccess = mergeAccess(existing.access, extension.access)
-
         // Merge MCP config
         const mergedMcp = extension.mcp
           ? {
@@ -221,7 +207,6 @@ export async function executePlugins(config: OpenSaasConfig): Promise<OpenSaasCo
           ...existing,
           fields: mergedFields,
           hooks: mergedHooks,
-          access: mergedAccess,
           mcp: mergedMcp,
         }
       },

package/src/config/types.ts

@@ -2437,8 +2437,21 @@ export type Plugin = {
    * Optional: Provide runtime services
    * Called when creating context to provide plugin-specific services
    * Return value is stored in context.plugins[pluginName]
-   */
-  runtime?: (context: import('../access/types.js').AccessContext) => unknown
+   *
+   * `sudo` returns an access-bypassing (but still hook-firing) `AccessContext`
+   * for the same request — use `sudo().db` for reads/writes that must not
+   * depend on the caller's own list access policy (e.g. an identity lookup
+   * like "who is this session"). Deliberately NOT a method on `AccessContext`
+   * itself — a self-referential `sudo(): AccessContext` field on that shared,
+   * widely-instantiated interface tripped up TypeScript's structural checking
+   * of unrelated generated Prisma types elsewhere (nullable JSON `CreateInput`
+   * fields) in a downstream app; passing it as a plain second argument avoids
+   * that recursion entirely.
+   */
+  runtime?: (
+    context: import('../access/types.js').AccessContext,
+    sudo: () => import('../access/types.js').AccessContext,
+  ) => unknown
 
   /**
    * Optional: Type metadata for runtime services

package/src/context/index.ts

@@ -393,7 +393,12 @@ export function getContext<
     for (const plugin of pluginsToExecute) {
       if (plugin.runtime) {
         try {
-          context.plugins[plugin.name] = plugin.runtime(context)
+          // Passed as a plain second argument rather than a method on
+          // `context` itself — see the `sudo` param doc on `Plugin['runtime']`.
+          context.plugins[plugin.name] = plugin.runtime(
+            context,
+            () => sudo() as unknown as AccessContext<TPrisma>,
+          )
         } catch (error) {
           console.error(`Error executing runtime for plugin "${plugin.name}":`, error)
           // Continue with other plugins even if one fails

package/src/query/relationship-options.test.ts

@@ -39,6 +39,13 @@ function makeConfig(): OpenSaasConfig {
         ui: { labelField: 'rank' },
         access: { operation: { query: () => true } },
       },
+      VirtualLabel: {
+        fields: {
+          displayName: { type: 'virtual', virtual: true },
+        },
+        ui: { labelField: 'displayName' },
+        access: { operation: { query: () => true } },
+      },
     },
   } as unknown as OpenSaasConfig
 }
@@ -99,6 +106,36 @@ describe('getRelationshipOptions', () => {
     expect(call.orderBy).toEqual({ rank: 'asc' })
   })
 
+  it('falls back to ordering by id when the label field is virtual (no backing column)', async () => {
+    const rows = [{ id: 'v1', displayName: 'Computed One' }]
+    const delegate = makeDelegate(rows)
+    const context = makeContext({ virtualLabel: delegate })
+    const config = makeConfig()
+
+    const result = await getRelationshipOptions(context, config, 'VirtualLabel', { search: 'One' })
+
+    const call = delegate.findMany.mock.calls[0][0] as Record<string, unknown>
+    // Virtual label fields have no backing column, so ordering by them would
+    // 500 in Prisma — order by id instead, and skip the text `contains` filter.
+    expect(call.orderBy).toEqual({ id: 'asc' })
+    expect(call.where).toBeUndefined()
+    expect(result).toEqual([{ id: 'v1', label: 'Computed One' }])
+  })
+
+  it('treats a field flagged virtual via type alone as non-orderable (orders by id)', async () => {
+    const config = makeConfig()
+    // Only `type: 'virtual'` is set here (no `virtual: true`) to lock in the
+    // discriminator against future refactors.
+    ;(config.lists.VirtualLabel.fields.displayName as { virtual?: boolean }).virtual = undefined
+    const delegate = makeDelegate([{ id: 'v1', displayName: 'Computed One' }])
+    const context = makeContext({ virtualLabel: delegate })
+
+    await getRelationshipOptions(context, config, 'VirtualLabel', { search: 'One' })
+
+    const call = delegate.findMany.mock.calls[0][0] as Record<string, unknown>
+    expect(call.orderBy).toEqual({ id: 'asc' })
+  })
+
   it('unions currently-selected ids even when beyond take / not matching search', async () => {
     // The bounded/search-scoped query only returns a1 (mimicking take:1 + search).
     const primaryDelegate = makeDelegate([authors[0]])

package/src/query/relationship-options.ts

@@ -44,13 +44,21 @@ export async function getRelationshipOptions(
   })
 
   const { search, take = DEFAULT_TAKE, selectedIds = [] } = args
-  const labelFieldConfig = relatedListConfig.fields[labelField] as { type?: string } | undefined
+  const labelFieldConfig = relatedListConfig.fields[labelField] as
+    { type?: string; virtual?: boolean } | undefined
   const where =
     search && labelFieldConfig?.type === 'text' ? { [labelField]: { contains: search } } : undefined
 
+  // Virtual/computed label fields (resolved at read time via `resolveOutput`)
+  // have no backing database column, so passing them into `orderBy` fails
+  // Prisma validation and 500s the request. Fall back to ordering by `id` —
+  // always a real, orderable column — whenever the label field is virtual.
+  const isVirtualLabel = labelFieldConfig?.type === 'virtual' || labelFieldConfig?.virtual === true
+  const orderBy: Record<string, 'asc'> = isVirtualLabel ? { id: 'asc' } : { [labelField]: 'asc' }
+
   const primary = await runQuery(context, relatedListKey, fragment, {
     where,
-    orderBy: { [labelField]: 'asc' },
+    orderBy,
     take,
   })
 

package/tests/plugin-engine.test.ts

@@ -681,8 +681,8 @@ describe('Plugin Engine', () => {
     })
   })
 
-  describe('access control merging', () => {
-    test('merges access control from plugins', async () => {
+  describe('access control guardrail (ADR-0013)', () => {
+    test('throws when an extension carries operation access for a pre-existing list', async () => {
       const plugin: Plugin = {
         name: 'test-plugin',
         init: async (context) => {
@@ -711,23 +711,19 @@ describe('Plugin Engine', () => {
         plugins: [plugin],
       }
 
-      const result = await executePlugins(config)
-
-      expect(result.lists.Post.access?.operation?.query).toBeDefined()
-      expect(result.lists.Post.access?.operation?.create).toBeDefined()
-      expect(result.lists.Post.access?.operation?.update).toBeDefined()
+      await expect(executePlugins(config)).rejects.toThrow(
+        'Plugin "test-plugin" tried to set operation-level access while extending list "Post"',
+      )
     })
 
-    test('plugin access control overrides existing', async () => {
-      const pluginQuery = vi.fn(() => false)
-
+    test('extension attempting to override existing access throws instead of silently winning', async () => {
       const plugin: Plugin = {
         name: 'test-plugin',
         init: async (context) => {
           context.extendList('Post', {
             access: {
               operation: {
-                query: pluginQuery,
+                query: () => false,
               },
             },
           })
@@ -750,10 +746,67 @@ describe('Plugin Engine', () => {
         plugins: [plugin],
       }
 
+      await expect(executePlugins(config)).rejects.toThrow('Post')
+
+      // The host's access is untouched — the throw happens before any mutation.
+      expect(config.lists.Post.access?.operation?.query).toBe(originalQuery)
+    })
+
+    test('extension providing only fields/hooks for a pre-existing list leaves its access untouched', async () => {
+      const originalQuery = vi.fn(() => true)
+
+      const plugin: Plugin = {
+        name: 'test-plugin',
+        init: async (context) => {
+          context.extendList('Post', {
+            fields: { views: integer() },
+          })
+        },
+      }
+
+      const config: OpenSaasConfig = {
+        lists: {
+          Post: {
+            fields: { title: text() },
+            access: {
+              operation: {
+                query: originalQuery,
+              },
+            },
+          },
+        },
+        plugins: [plugin],
+      }
+
+      const result = await executePlugins(config)
+
+      expect(result.lists.Post.fields.views).toBeDefined()
+      expect(result.lists.Post.access?.operation?.query).toBe(originalQuery)
+    })
+
+    test('a plugin creating a new list may still set its access via addList', async () => {
+      const plugin: Plugin = {
+        name: 'test-plugin',
+        init: async (context) => {
+          context.addList('Widget', {
+            fields: { name: text() },
+            access: {
+              operation: {
+                query: () => true,
+              },
+            },
+          })
+        },
+      }
+
+      const config: OpenSaasConfig = {
+        lists: {},
+        plugins: [plugin],
+      }
+
       const result = await executePlugins(config)
 
-      // Plugin's access control should override original
-      expect(result.lists.Post.access?.operation?.query).toBe(pluginQuery)
+      expect(result.lists.Widget.access?.operation?.query).toBeDefined()
     })
   })
 

package/tests/sudo.test.ts

@@ -3,6 +3,8 @@ import { getContext } from '../src/context/index.js'
 import { config, list } from '../src/config/index.js'
 import { text, integer, relationship } from '../src/fields/index.js'
 import type { PrismaClient } from '@prisma/client'
+import type { Plugin } from '../src/config/types.js'
+import type { AccessContext } from '../src/access/types.js'
 
 describe('Sudo Context', () => {
   // Mock Prisma client
@@ -624,4 +626,51 @@ describe('Sudo Context', () => {
       ).rejects.toThrow('Access denied')
     })
   })
+
+  describe('Plugin runtime sudo access', () => {
+    // A plugin's `runtime(context, sudo)` factory receives a `sudo` helper as a
+    // plain second argument — NOT a method on `AccessContext` itself. A
+    // self-referential `sudo(): AccessContext` field on that shared, widely
+    // instantiated interface was found to break TypeScript's structural
+    // checking of unrelated generated Prisma types in a downstream app
+    // (nullable JSON `CreateInput` fields); passing it as a separate argument
+    // avoids that recursion while still giving plugins (e.g. the auth
+    // plugin's getUser/getCurrentUser, see ADR-0013) an access-bypassing
+    // identity-lookup path.
+    it('passes a working sudo() as the second argument to plugin.runtime()', async () => {
+      let capturedSudo: (() => AccessContext<typeof mockPrisma>) | undefined
+
+      const plugin: Plugin = {
+        name: 'test-plugin',
+        init: async () => {},
+        runtime: (_context, sudo) => {
+          capturedSudo = sudo as () => AccessContext<typeof mockPrisma>
+          return {}
+        },
+      }
+
+      const pluginConfig = await config({
+        db: { provider: 'sqlite' },
+        plugins: [plugin],
+        lists: {
+          Post: list({
+            fields: { title: text({ validation: { isRequired: true } }) },
+            // Closed list: only sudo() should be able to read from it.
+            access: { operation: { query: () => false } },
+          }),
+        },
+      })
+
+      mockPrisma.post.findMany.mockResolvedValue([{ id: '1', title: 'Test Post' }])
+
+      getContext(pluginConfig, mockPrisma, null)
+
+      expect(capturedSudo).toBeTypeOf('function')
+
+      const sudoContext = capturedSudo!()
+      const sudoResult = await sudoContext.db.post.findMany()
+      expect(sudoResult).toHaveLength(1)
+      expect(sudoResult[0].title).toBe('Test Post')
+    })
+  })
 })