@opensaas/stack-core 0.20.1 → 0.21.0

package/dist/validation/field-config.js

@@ -0,0 +1,100 @@
+/**
+ * Describe a field for an error message. Falls back to a literal when a
+ * `type`-less value slips through (e.g. a malformed third-party field).
+ */
+function describeFieldType(field) {
+    return typeof field.type === 'string' && field.type.length > 0 ? field.type : 'unknown';
+}
+/**
+ * Type-safe probe for a function-valued property on a field config.
+ *
+ * The three scalar contract methods live on `BaseFieldConfig` and are checked
+ * directly. `getPrismaRelation` only exists on the relationship field variant,
+ * so it is probed structurally here without widening the public type or
+ * reaching for a cast.
+ */
+function hasFieldMethod(field, method) {
+    const value = Reflect.get(field, method);
+    return typeof value === 'function';
+}
+/**
+ * Build the canonical error message for a missing contract method.
+ */
+function buildMessage(fieldType, method, fieldKey, listKey) {
+    const location = listKey ? `Field "${listKey}.${fieldKey}"` : `Field "${fieldKey}"`;
+    return (`${location} (type "${fieldType}") is not self-contained: it does not implement ` +
+        `${method}(). Field builders must provide this method so the generator can ` +
+        `produce schema and types without inspecting field internals.`);
+}
+/**
+ * Validate a single field against the self-containment contract.
+ *
+ * The contract is conditional on field kind, mirroring exactly where the
+ * generators delegate:
+ *
+ *   - `relationship` fields contribute schema via `getPrismaRelation` and are
+ *     skipped by the scalar Prisma/TypeScript/Zod paths, so only
+ *     `getPrismaRelation` is required.
+ *   - `virtual` fields are not stored in the database, so `getPrismaType` is
+ *     legitimately absent; they must still provide `getTypeScriptType` and
+ *     `getZodSchema`.
+ *   - every other (stored scalar) field must provide `getPrismaType`,
+ *     `getTypeScriptType`, and `getZodSchema`.
+ *
+ * @param field - The field config produced by a field builder.
+ * @param fieldKey - The field's key within its list (for messages).
+ * @param listKey - The owning list's key (optional, for messages).
+ * @returns Zero or more structured errors; empty means the field is compliant.
+ */
+export function validateFieldConfig(field, fieldKey, listKey) {
+    const errors = [];
+    const fieldType = describeFieldType(field);
+    const requireMethod = (method) => {
+        if (!hasFieldMethod(field, method)) {
+            errors.push({
+                listKey,
+                fieldKey,
+                fieldType,
+                missingMethod: method,
+                message: buildMessage(fieldType, method, fieldKey, listKey),
+            });
+        }
+    };
+    if (field.type === 'relationship') {
+        // Relationships render through the relationship path only.
+        requireMethod('getPrismaRelation');
+        return errors;
+    }
+    if (field.virtual === true || field.type === 'virtual') {
+        // Virtual fields are not persisted, so getPrismaType is intentionally absent.
+        requireMethod('getTypeScriptType');
+        requireMethod('getZodSchema');
+        return errors;
+    }
+    // Stored scalar fields must implement the full generation contract.
+    requireMethod('getPrismaType');
+    requireMethod('getTypeScriptType');
+    requireMethod('getZodSchema');
+    return errors;
+}
+/**
+ * Validate every field across every list in a config.
+ *
+ * Intended to run once, before any generation, so a misimplemented field
+ * surfaces a clear per-field message instead of a deep generator stack trace.
+ *
+ * @param config - The fully resolved OpenSaas config.
+ * @returns All self-containment violations, flattened across lists and fields.
+ */
+export function validateConfigFields(config) {
+    const errors = [];
+    for (const [listKey, listConfig] of Object.entries(config.lists)) {
+        if (!listConfig?.fields)
+            continue;
+        for (const [fieldKey, fieldConfig] of Object.entries(listConfig.fields)) {
+            errors.push(...validateFieldConfig(fieldConfig, fieldKey, listKey));
+        }
+    }
+    return errors;
+}
+//# sourceMappingURL=field-config.js.map

package/dist/validation/field-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-config.js","sourceRoot":"","sources":["../../src/validation/field-config.ts"],"names":[],"mappings":"AAyBA;;;GAGG;AACH,SAAS,iBAAiB,CAAC,KAAkB;IAC3C,OAAO,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAA;AACzF,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,cAAc,CAAC,KAAkB,EAAE,MAAc;IACxD,MAAM,KAAK,GAAY,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;IACjD,OAAO,OAAO,KAAK,KAAK,UAAU,CAAA;AACpC,CAAC;AAED;;GAEG;AACH,SAAS,YAAY,CACnB,SAAiB,EACjB,MAAmD,EACnD,QAAgB,EAChB,OAAgB;IAEhB,MAAM,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC,UAAU,OAAO,IAAI,QAAQ,GAAG,CAAC,CAAC,CAAC,UAAU,QAAQ,GAAG,CAAA;IACnF,OAAO,CACL,GAAG,QAAQ,WAAW,SAAS,kDAAkD;QACjF,GAAG,MAAM,mEAAmE;QAC5E,8DAA8D,CAC/D,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAAkB,EAClB,QAAgB,EAChB,OAAgB;IAEhB,MAAM,MAAM,GAAiC,EAAE,CAAA;IAC/C,MAAM,SAAS,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAA;IAE1C,MAAM,aAAa,GAAG,CAAC,MAAmD,EAAQ,EAAE;QAClF,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE,CAAC;YACnC,MAAM,CAAC,IAAI,CAAC;gBACV,OAAO;gBACP,QAAQ;gBACR,SAAS;gBACT,aAAa,EAAE,MAAM;gBACrB,OAAO,EAAE,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC;aAC5D,CAAC,CAAA;QACJ,CAAC;IACH,CAAC,CAAA;IAED,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;QAClC,2DAA2D;QAC3D,aAAa,CAAC,mBAAmB,CAAC,CAAA;QAClC,OAAO,MAAM,CAAA;IACf,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,KAAK,IAAI,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QACvD,8EAA8E;QAC9E,aAAa,CAAC,mBAAmB,CAAC,CAAA;QAClC,aAAa,CAAC,cAAc,CAAC,CAAA;QAC7B,OAAO,MAAM,CAAA;IACf,CAAC;IAED,oEAAoE;IACpE,aAAa,CAAC,eAAe,CAAC,CAAA;IAC9B,aAAa,CAAC,mBAAmB,CAAC,CAAA;IAClC,aAAa,CAAC,cAAc,CAAC,CAAA;IAE7B,OAAO,MAAM,CAAA;AACf,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAsB;IACzD,MAAM,MAAM,GAAiC,EAAE,CAAA;IAE/C,KAAK,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QACjE,IAAI,CAAC,UAAU,EAAE,MAAM;YAAE,SAAQ;QACjC,KAAK,MAAM,CAAC,QAAQ,EAAE,WAAW,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YACxE,MAAM,CAAC,IAAI,CAAC,GAAG,mBAAmB,CAAC,WAAW,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAA;QACrE,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/validation/field-config.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=field-config.test.d.ts.map

package/dist/validation/field-config.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-config.test.d.ts","sourceRoot":"","sources":["../../src/validation/field-config.test.ts"],"names":[],"mappings":""}

package/dist/validation/field-config.test.js

@@ -0,0 +1,159 @@
+import { describe, it, expect } from 'vitest';
+import { validateFieldConfig, validateConfigFields } from './field-config.js';
+import { text, integer, checkbox, timestamp, password, select, json, relationship, virtual, } from '../fields/index.js';
+describe('validateFieldConfig', () => {
+    describe('well-formed fields pass', () => {
+        it.each([
+            ['text', text()],
+            ['integer', integer()],
+            ['checkbox', checkbox()],
+            ['timestamp', timestamp()],
+            ['password', password()],
+            ['select', select({ options: [{ label: 'A', value: 'a' }] })],
+            ['json', json()],
+        ])('a built-in %s field is self-contained', (_name, field) => {
+            expect(validateFieldConfig(field, 'myField', 'MyList')).toEqual([]);
+        });
+        it('a relationship field is self-contained via getPrismaRelation', () => {
+            const field = relationship({ ref: 'User.posts' });
+            expect(validateFieldConfig(field, 'author', 'Post')).toEqual([]);
+        });
+        it('a virtual field is self-contained without getPrismaType', () => {
+            const field = virtual({
+                type: 'string',
+                hooks: { resolveOutput: () => 'x' },
+            });
+            expect(validateFieldConfig(field, 'fullName', 'User')).toEqual([]);
+        });
+    });
+    describe('missing scalar contract methods fail', () => {
+        it('reports a missing getPrismaType naming the list, field, and method', () => {
+            const field = text();
+            delete field.getPrismaType;
+            const errors = validateFieldConfig(field, 'title', 'Post');
+            expect(errors).toHaveLength(1);
+            expect(errors[0]).toMatchObject({
+                listKey: 'Post',
+                fieldKey: 'title',
+                fieldType: 'text',
+                missingMethod: 'getPrismaType',
+            });
+            expect(errors[0].message).toContain('Post.title');
+            expect(errors[0].message).toContain('getPrismaType');
+            expect(errors[0].message).toContain('not self-contained');
+        });
+        it('reports a missing getTypeScriptType naming the method', () => {
+            const field = text();
+            delete field.getTypeScriptType;
+            const errors = validateFieldConfig(field, 'title', 'Post');
+            expect(errors).toHaveLength(1);
+            expect(errors[0].missingMethod).toBe('getTypeScriptType');
+            expect(errors[0].message).toContain('getTypeScriptType');
+        });
+        it('reports a missing getZodSchema naming the method', () => {
+            const field = text();
+            delete field.getZodSchema;
+            const errors = validateFieldConfig(field, 'title', 'Post');
+            expect(errors).toHaveLength(1);
+            expect(errors[0].missingMethod).toBe('getZodSchema');
+            expect(errors[0].message).toContain('getZodSchema');
+        });
+        it('reports every missing method when a field implements none', () => {
+            const field = { type: 'custom' };
+            const errors = validateFieldConfig(field, 'mystery', 'Widget');
+            expect(errors.map((e) => e.missingMethod).sort()).toEqual([
+                'getPrismaType',
+                'getTypeScriptType',
+                'getZodSchema',
+            ]);
+            for (const error of errors) {
+                expect(error.message).toContain('Widget.mystery');
+                expect(error.message).toContain('custom');
+            }
+        });
+        it('works without a listKey (bare field validation)', () => {
+            const field = { type: 'custom' };
+            const errors = validateFieldConfig(field, 'mystery');
+            expect(errors).toHaveLength(3);
+            expect(errors[0].listKey).toBeUndefined();
+            expect(errors[0].message).toContain('Field "mystery"');
+        });
+    });
+    describe('relationship and virtual variants', () => {
+        it('reports a relationship missing getPrismaRelation', () => {
+            const field = { type: 'relationship' };
+            const errors = validateFieldConfig(field, 'author', 'Post');
+            expect(errors).toHaveLength(1);
+            expect(errors[0].missingMethod).toBe('getPrismaRelation');
+            expect(errors[0].message).toContain('Post.author');
+        });
+        it('reports a virtual field missing getTypeScriptType and getZodSchema', () => {
+            const field = { type: 'virtual', virtual: true };
+            const errors = validateFieldConfig(field, 'fullName', 'User');
+            expect(errors.map((e) => e.missingMethod).sort()).toEqual([
+                'getTypeScriptType',
+                'getZodSchema',
+            ]);
+        });
+        it('does not require getPrismaType for virtual fields', () => {
+            const field = { type: 'virtual', virtual: true };
+            const errors = validateFieldConfig(field, 'fullName', 'User');
+            expect(errors.some((e) => e.missingMethod === 'getPrismaType')).toBe(false);
+        });
+    });
+});
+describe('validateConfigFields', () => {
+    it('returns no errors for a fully compliant config', () => {
+        const config = {
+            db: {
+                provider: 'sqlite',
+                prismaClientConstructor: () => null,
+            },
+            lists: {
+                User: {
+                    fields: {
+                        name: text({ validation: { isRequired: true } }),
+                        posts: relationship({ ref: 'Post.author', many: true }),
+                    },
+                },
+                Post: {
+                    fields: {
+                        title: text(),
+                        author: relationship({ ref: 'User.posts' }),
+                    },
+                },
+            },
+        };
+        expect(validateConfigFields(config)).toEqual([]);
+    });
+    it('collects per-field errors across every list and names each location', () => {
+        const brokenTitle = text();
+        delete brokenTitle.getPrismaType;
+        const brokenName = text();
+        delete brokenName.getZodSchema;
+        const config = {
+            db: {
+                provider: 'sqlite',
+                prismaClientConstructor: () => null,
+            },
+            lists: {
+                User: {
+                    fields: {
+                        name: brokenName,
+                    },
+                },
+                Post: {
+                    fields: {
+                        title: brokenTitle,
+                    },
+                },
+            },
+        };
+        const errors = validateConfigFields(config);
+        expect(errors).toHaveLength(2);
+        const byField = Object.fromEntries(errors.map((e) => [`${e.listKey}.${e.fieldKey}`, e]));
+        expect(byField['User.name'].missingMethod).toBe('getZodSchema');
+        expect(byField['Post.title'].missingMethod).toBe('getPrismaType');
+    });
+});
+//# sourceMappingURL=field-config.test.js.map

package/dist/validation/field-config.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-config.test.js","sourceRoot":"","sources":["../../src/validation/field-config.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensaas/stack-core",
-  "version": "0.20.1",
+  "version": "0.21.0",
   "description": "Core stack for OpenSaas - schema definition, access control, and runtime utilities",
   "type": "module",
   "main": "./dist/index.js",
@@ -14,6 +14,14 @@
       "types": "./dist/fields/index.d.ts",
       "default": "./dist/fields/index.js"
     },
+    "./extend": {
+      "types": "./dist/extend.d.ts",
+      "default": "./dist/extend.js"
+    },
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "default": "./dist/internal.js"
+    },
     "./mcp": {
       "types": "./dist/mcp/index.d.ts",
       "default": "./dist/mcp/index.js"
@@ -48,8 +56,8 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@prisma/client": "^7.4.2",
-    "@types/node": "^24.12.0",
+    "@prisma/client": "^7.8.0",
+    "@types/node": "^25.9.1",
     "@vitest/coverage-v8": "^4.0.18",
     "typescript": "^5.9.3",
     "vitest": "^4.1.0"

package/src/access/access-filter.ts

@@ -0,0 +1,97 @@
+import type { Session, AccessContext, PrismaFilter } from './types.js'
+import type { OpenSaasConfig, FieldConfig } from '../config/types.js'
+import { checkAccess, getRelatedListConfig } from './engine.js'
+
+/**
+ * Access Filter — phase 1 of the two-phase read (pre-query).
+ *
+ * This module scopes which rows and relationships the database is allowed to
+ * return, before the query runs. It evaluates *operation-level* `query` access
+ * on related lists and turns the results into a Prisma `include`/`where` clause,
+ * so denied rows and relations never leave the database.
+ *
+ * Phase 2 (post-query field stripping + `resolveOutput` + virtual computation)
+ * lives in `field-visibility.ts`. The two phases cannot be merged: virtual
+ * fields are computed in JavaScript and post-query field access can depend on
+ * the fetched row, neither of which is expressible in SQL. See
+ * `docs/adr/0001-access-control-is-a-two-phase-read.md` and the access-control
+ * glossary in `CONTEXT.md`.
+ */
+
+/**
+ * Build Prisma include object with access control filters
+ * This allows us to filter relationships at the database level instead of in memory
+ */
+export async function buildIncludeWithAccessControl(
+  fieldConfigs: Record<string, FieldConfig>,
+  args: {
+    session: Session | null
+    context: AccessContext
+  },
+  config: OpenSaasConfig,
+  depth: number = 0,
+) {
+  const MAX_DEPTH = 5
+  if (depth >= MAX_DEPTH) {
+    return undefined
+  }
+
+  // Skip auto-including relationships when inside a resolveOutput hook
+  // This prevents infinite loops when hooks make DB queries that include
+  // relationships back to the same entity (e.g., User virtual field queries Posts
+  // which includes author back to User, triggering the virtual field again)
+  if (args.context._resolveOutputCounter.depth > 0) {
+    return undefined
+  }
+
+  type IncludeEntry = boolean | { where?: PrismaFilter; include?: Record<string, IncludeEntry> }
+
+  const include: Record<string, IncludeEntry> = {}
+  let hasRelationships = false
+
+  for (const [fieldName, fieldConfig] of Object.entries(fieldConfigs)) {
+    if (fieldConfig?.type === 'relationship' && 'ref' in fieldConfig && fieldConfig.ref) {
+      hasRelationships = true
+      const relatedConfig = getRelatedListConfig(fieldConfig.ref as string, config)
+
+      if (relatedConfig) {
+        // Check query access for the related list
+        const queryAccess = relatedConfig.listConfig.access?.operation?.query
+        const accessResult = await checkAccess(queryAccess, {
+          session: args.session,
+          context: args.context,
+        })
+
+        // If access is completely denied, exclude this relationship
+        if (accessResult === false) {
+          continue
+        }
+
+        // Build the include entry
+        const includeEntry: Record<string, unknown> = {}
+
+        // If access returns a filter, add it to the where clause
+        if (typeof accessResult === 'object') {
+          includeEntry.where = accessResult
+        }
+
+        // Recursively build nested includes
+        const nestedInclude = await buildIncludeWithAccessControl(
+          relatedConfig.listConfig.fields,
+          args,
+          config,
+          depth + 1,
+        )
+
+        if (nestedInclude && Object.keys(nestedInclude).length > 0) {
+          includeEntry.include = nestedInclude
+        }
+
+        // Add to include object
+        include[fieldName] = Object.keys(includeEntry).length > 0 ? includeEntry : true
+      }
+    }
+  }
+
+  return hasRelationships ? include : undefined
+}