@aphexcms/cms-core 2.0.9 → 2.0.11

package/dist/local-api/collection-api.js

@@ -2,12 +2,41 @@
 //
 // Collection API - provides type-safe CRUD operations for a single collection
 import { validateDocumentData } from '../field-validation/utils.js';
+import { hiddenReadFields, hiddenWriteFields, dropLockedWrites, stripHiddenFields } from '../field-access.js';
+const EMPTY_SET = new Set();
+/**
+ * Re-project a FindResult through a hidden-fields filter without mutating
+ * the shared (potentially cached) original.
+ */
+function applyHiddenToResult(result, hidden) {
+    if (hidden.size === 0)
+        return result;
+    return {
+        ...result,
+        docs: result.docs.map((d) => applyHiddenToDoc(d, hidden))
+    };
+}
+function applyHiddenToDoc(doc, hidden) {
+    if (!doc || typeof doc !== 'object')
+        return doc;
+    const copy = {};
+    for (const [key, value] of Object.entries(doc)) {
+        if (hidden.has(key))
+            continue;
+        copy[key] = value;
+    }
+    return copy;
+}
 /**
  * Transform a raw database document into a typed document with data extracted
- * based on perspective (draft or published)
+ * based on perspective (draft or published). Optionally strips field-level
+ * read-restricted fields from the data payload.
  */
-function transformDocument(doc, perspective = 'draft') {
-    const data = perspective === 'draft' ? doc.draftData : doc.publishedData;
+function transformDocument(doc, perspective = 'draft', hiddenFields) {
+    const raw = perspective === 'draft' ? doc.draftData : doc.publishedData;
+    const data = hiddenFields && hiddenFields.size > 0
+        ? stripHiddenFields(raw, hiddenFields)
+        : raw;
     // Merge document metadata with the content data
     return {
         id: doc.id,
@@ -77,11 +106,15 @@ export class CollectionAPI {
         // Permission check (unless overrideAccess)
         await this.permissions.canRead(context, this.collectionName);
         const perspective = options.perspective || 'draft';
+        // Field-level access: compute per-request so two users with different
+        // roles see different projections even when the underlying cache hit
+        // is shared. Cached payloads are stored unfiltered for this reason.
+        const hidden = this.resolveHiddenReadFields(context);
         // Check cache for published queries
         if (perspective === 'published' && this.documentCache) {
             const cached = await this.documentCache.getQuery(context.organizationId, this.collectionName, options);
             if (cached)
-                return cached;
+                return applyHiddenToResult(cached, hidden);
         }
         // Resolve org IDs via hierarchy service (cached) and pass directly —
         // this avoids the adapter opening a transaction just to set RLS context
@@ -91,17 +124,28 @@ export class CollectionAPI {
             findOptions.filterOrganizationIds = orgIds;
         }
         const result = await this.databaseAdapter.findManyDocAdvanced(context.organizationId, this.collectionName, findOptions);
-        // Transform documents to extract data based on perspective
-        const transformedDocs = result.docs.map((doc) => transformDocument(doc, perspective));
-        const findResult = {
+        // Transform documents to extract data based on perspective.
+        // Cache the unfiltered version; return the filtered one.
+        const unfilteredDocs = result.docs.map((doc) => transformDocument(doc, perspective));
+        const unfilteredResult = {
             ...result,
-            docs: transformedDocs
+            docs: unfilteredDocs
         };
-        // Populate cache for published queries
+        // Populate cache for published queries (unfiltered payload)
         if (perspective === 'published' && this.documentCache) {
-            await this.documentCache.setQuery(context.organizationId, this.collectionName, options, findResult);
+            await this.documentCache.setQuery(context.organizationId, this.collectionName, options, unfilteredResult);
         }
-        return findResult;
+        return applyHiddenToResult(unfilteredResult, hidden);
+    }
+    resolveHiddenReadFields(context) {
+        if (context.overrideAccess)
+            return EMPTY_SET;
+        return hiddenReadFields(this._schema, context.auth);
+    }
+    resolveHiddenWriteFields(context) {
+        if (context.overrideAccess)
+            return EMPTY_SET;
+        return hiddenWriteFields(this._schema, context.auth);
     }
     /**
      * Find a single document by ID
@@ -119,11 +163,12 @@ export class CollectionAPI {
         // Permission check (unless overrideAccess)
         await this.permissions.canRead(context, this.collectionName);
         const perspective = options?.perspective || 'draft';
+        const hidden = this.resolveHiddenReadFields(context);
         // Check cache for published lookups
         if (perspective === 'published' && this.documentCache) {
             const cached = await this.documentCache.getDocument(context.organizationId, id);
             if (cached)
-                return cached;
+                return applyHiddenToDoc(cached, hidden);
         }
         // Resolve org IDs via hierarchy service (cached) — avoids RLS transaction
         const findOptions = { ...options };
@@ -135,11 +180,13 @@ export class CollectionAPI {
         if (!result) {
             return null;
         }
-        const transformed = transformDocument(result, perspective);
-        // Populate cache for published lookups
+        // Cache the unfiltered projection; apply hidden fields per-caller.
+        const unfiltered = transformDocument(result, perspective);
+        // Populate cache for published lookups (unfiltered payload)
         if (perspective === 'published' && this.documentCache) {
-            await this.documentCache.setDocument(context.organizationId, id, transformed);
+            await this.documentCache.setDocument(context.organizationId, id, unfiltered);
         }
+        const transformed = applyHiddenToDoc(unfiltered, hidden);
         return transformed;
     }
     /**
@@ -177,9 +224,16 @@ export class CollectionAPI {
      */
     async create(context, data, options) {
         // Permission check (unless overrideAccess)
-        await this.permissions.canWrite(context, this.collectionName);
+        await this.permissions.canCreate(context, this.collectionName);
+        // Drop any writes targeting field-locked names before validation.
+        // A caller with collection-level update may still lack write access on
+        // a specific field; silently dropping keeps the server authoritative.
+        const locked = this.resolveHiddenWriteFields(context);
+        const filteredData = dropLockedWrites(data, locked);
         // Validate and normalize data (dates converted to ISO)
-        const validationResult = await validateDocumentData(this._schema, data, data);
+        const validationResult = await validateDocumentData(this._schema, filteredData, {
+            context: filteredData
+        });
         if (options?.publish) {
             await this.permissions.canPublish(context, this.collectionName);
             // Block publish if validation fails
@@ -234,13 +288,19 @@ export class CollectionAPI {
      * ```
      */
     async update(context, id, data, options) {
-        // Permission check (unless overrideAccess)
-        await this.permissions.canWrite(context, this.collectionName);
-        // Get existing document to merge with updates
+        // Fetch the doc first so ownership policies have access to the target.
+        // A missing doc still returns null below; capability/role rules stay
+        // unaffected by the reorder.
         const existingDoc = await this.databaseAdapter.findByDocIdAdvanced(context.organizationId, id);
         if (!existingDoc) {
             return null;
         }
+        await this.permissions.canUpdate(context, this.collectionName, existingDoc);
+        // Drop writes targeting field-locked names so a caller with
+        // collection-level update can't bypass field-level restrictions.
+        // Field-locked values stay at their existing stored value via the merge.
+        const locked = this.resolveHiddenWriteFields(context);
+        const filteredData = dropLockedWrites(data, locked);
         // Merge existing data with updates, but only keep fields defined in schema
         // This prevents orphaned fields from persisting when schema changes
         const schemaFieldNames = new Set(this._schema.fields.map((f) => f.name));
@@ -251,8 +311,8 @@ export class CollectionAPI {
                 cleanedExisting[key] = value;
             }
         }
-        // Merge cleaned existing data with new updates
-        const mergedData = { ...cleanedExisting, ...data };
+        // Merge cleaned existing data with filtered updates
+        const mergedData = { ...cleanedExisting, ...filteredData };
         // Validate and normalize the merged data
         const validationResult = await validateDocumentData(this._schema, mergedData, mergedData);
         // Update draft with normalized data (dates in ISO format)
@@ -264,7 +324,7 @@ export class CollectionAPI {
             return null;
         }
         if (options?.publish) {
-            await this.permissions.canPublish(context, this.collectionName);
+            await this.permissions.canPublish(context, this.collectionName, document);
             // Block publish if validation fails
             if (!validationResult.isValid) {
                 const errorMessage = validationResult.errors
@@ -304,8 +364,13 @@ export class CollectionAPI {
      * ```
      */
     async delete(context, id) {
-        // Permission check (unless overrideAccess)
-        await this.permissions.canDelete(context, this.collectionName);
+        // Fetch the target so ownership policies have a doc to inspect. For
+        // role/capability rules this extra read is a small cost; ergonomic
+        // wins outweigh it for operations that are rare by nature.
+        const existing = await this.databaseAdapter.findByDocIdAdvanced(context.organizationId, id);
+        if (!existing)
+            return false;
+        await this.permissions.canDelete(context, this.collectionName, existing);
         const result = await this.databaseAdapter.deleteDocById(context.organizationId, id);
         // Invalidate cache for deleted document
         if (result && this.documentCache) {
@@ -326,13 +391,13 @@ export class CollectionAPI {
      * ```
      */
     async publish(context, id) {
-        // Permission check (unless overrideAccess)
-        await this.permissions.canPublish(context, this.collectionName);
-        // Get the document to access draft data for validation
+        // Fetch first so policies can inspect the target. Order matters here:
+        // 404s beat 403s for missing docs.
         const document = await this.databaseAdapter.findByDocIdAdvanced(context.organizationId, id);
         if (!document || !document.draftData) {
             throw new Error('Document not found or has no draft content to publish');
         }
+        await this.permissions.canPublish(context, this.collectionName, document);
         // Validate draft data (dates already in ISO, will be converted for validation)
         const validationResult = await validateDocumentData(this._schema, document.draftData, document.draftData);
         if (!validationResult.isValid) {
@@ -367,8 +432,11 @@ export class CollectionAPI {
      * ```
      */
     async unpublish(context, id) {
-        // Permission check (unless overrideAccess)
-        await this.permissions.canPublish(context, this.collectionName);
+        // Fetch target for policy inspection before mutating.
+        const existing = await this.databaseAdapter.findByDocIdAdvanced(context.organizationId, id);
+        if (!existing)
+            return null;
+        await this.permissions.canUnpublish(context, this.collectionName, existing);
         const document = await this.databaseAdapter.unpublishDoc(context.organizationId, id);
         if (!document) {
             return null;

package/dist/local-api/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/local-api/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C;;;GAGG;AACH,MAAM,WAAW,WAAW;IAE3B,CAAC,cAAc,EAAE,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;CAGjD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,QAAQ;IAWnB,OAAO,CAAC,MAAM;IAVR,WAAW,EAAE,WAAW,CAAqB;IACpD,OAAO,CAAC,WAAW,CAAkB;IACrC,OAAO,CAAC,aAAa,CAAyB;IAC9C,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,gBAAgB,CAAmB;IACpC,cAAc,EAAE,cAAc,CAAC;IACtC,OAAO,CAAC,WAAW,CAAoB;IACvC,OAAO,CAAC,OAAO,CAA0B;gBAGhC,MAAM,EAAE,SAAS,EACzB,WAAW,EAAE,eAAe,EAC5B,aAAa,CAAC,EAAE,eAAe;IAwBhC;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAgC7B;;;OAGG;IACH,OAAO,CAAC,UAAU;IAOlB;;OAEG;IACH,kBAAkB,IAAI,MAAM,EAAE;IAI9B;;OAEG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIpC;;OAEG;IACH,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAIzD;;;;OAIG;IACG,gBAAgB,CACrB,OAAO,EAAE,eAAe,EACxB,EAAE,EAAE,MAAM,EACV,OAAO,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,GACrC,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;CAetD;AAKD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAC7B,MAAM,EAAE,SAAS,EACjB,WAAW,EAAE,eAAe,EAC5B,aAAa,CAAC,EAAE,eAAe,GAC7B,QAAQ,CAGV;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,IAAI,QAAQ,CAKtC;AAGD,OAAO,EAAE,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACnE,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/local-api/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C;;;GAGG;AACH,MAAM,WAAW,WAAW;IAE3B,CAAC,cAAc,EAAE,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;CAGjD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,QAAQ;IAWnB,OAAO,CAAC,MAAM;IAVR,WAAW,EAAE,WAAW,CAAqB;IACpD,OAAO,CAAC,WAAW,CAAkB;IACrC,OAAO,CAAC,aAAa,CAAyB;IAC9C,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,gBAAgB,CAAmB;IACpC,cAAc,EAAE,cAAc,CAAC;IACtC,OAAO,CAAC,WAAW,CAAoB;IACvC,OAAO,CAAC,OAAO,CAA0B;gBAGhC,MAAM,EAAE,SAAS,EACzB,WAAW,EAAE,eAAe,EAC5B,aAAa,CAAC,EAAE,eAAe;IAwBhC;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAgD7B;;;OAGG;IACH,OAAO,CAAC,UAAU;IAOlB;;OAEG;IACH,kBAAkB,IAAI,MAAM,EAAE;IAI9B;;OAEG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIpC;;OAEG;IACH,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAIzD;;;;OAIG;IACG,gBAAgB,CACrB,OAAO,EAAE,eAAe,EACxB,EAAE,EAAE,MAAM,EACV,OAAO,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,GACrC,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;CAetD;AAKD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAC7B,MAAM,EAAE,SAAS,EACjB,WAAW,EAAE,eAAe,EAC5B,aAAa,CAAC,EAAE,eAAe,GAC7B,QAAQ,CAGV;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,IAAI,QAAQ,CAKtC;AAGD,OAAO,EAAE,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACnE,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/local-api/permissions.d.ts

@@ -1,45 +1,45 @@
 import type { LocalAPIContext } from './types.js';
 import type { SchemaType } from '../types/schemas.js';
+import type { Document } from '../types/document.js';
 import type { CMSConfig } from '../types/config.js';
-/**
- * Permission error thrown when access is denied
- */
 export declare class PermissionError extends Error {
     readonly operation: string;
     readonly resource: string;
     constructor(message: string, operation: string, resource: string);
 }
-/**
- * Checks permissions for Local API operations
- */
 export declare class PermissionChecker {
     private _config;
     private schemas;
     constructor(_config: CMSConfig, schemas: Map<string, SchemaType>);
-    /**
-     * Get the CMS config
-     * Available for future per-collection permission logic
-     */
     get config(): CMSConfig;
+    canRead(context: LocalAPIContext, collectionName: string, doc?: Document): Promise<void>;
+    canCreate(context: LocalAPIContext, collectionName: string): Promise<void>;
+    canUpdate(context: LocalAPIContext, collectionName: string, doc?: Document): Promise<void>;
     /**
-     * Check if the current context has read permissions for a collection
-     */
-    canRead(context: LocalAPIContext, collectionName: string): Promise<void>;
-    /**
-     * Check if the current context has write permissions (create/update)
-     */
-    canWrite(context: LocalAPIContext, collectionName: string): Promise<void>;
-    /**
-     * Check if the current context has delete permissions
-     */
-    canDelete(context: LocalAPIContext, collectionName: string): Promise<void>;
-    /**
-     * Check if the current context has publish permissions
+     * @deprecated Prefer `canCreate` or `canUpdate` — this method conflates the
+     * two and was only kept for legacy call sites. It now aliases `canUpdate`
+     * for safety (update is the more restrictive default for mutation).
      */
-    canPublish(context: LocalAPIContext, collectionName: string): Promise<void>;
+    canWrite(context: LocalAPIContext, collectionName: string, doc?: Document): Promise<void>;
+    canDelete(context: LocalAPIContext, collectionName: string, doc?: Document): Promise<void>;
+    canPublish(context: LocalAPIContext, collectionName: string, doc?: Document): Promise<void>;
+    canUnpublish(context: LocalAPIContext, collectionName: string, doc?: Document): Promise<void>;
+    validateCollection(collectionName: string): void;
+    private assert;
+    private logDenial;
+    private requireAuth;
     /**
-     * Validate that a collection exists in the schema
+     * Evaluate an access rule for a given operation.
+     *
+     * Three kinds of declared rules:
+     *   - `OrganizationRole[]` — role allowlist (as before).
+     *   - `(ctx) => boolean` — arbitrary policy, receives auth + optional doc.
+     *     Use for ownership rules like `doc.createdBy === auth.user.id`.
+     *   - `undefined` — fall back to capability check.
+     *
+     * A declared-but-excluded role/policy for a session caller is an explicit
+     * deny; the capability map does not re-grant access.
      */
-    validateCollection(collectionName: string): void;
+    private isAllowed;
 }
 //# sourceMappingURL=permissions.d.ts.map

package/dist/local-api/permissions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../../src/lib/local-api/permissions.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;GAEG;AACH,qBAAa,eAAgB,SAAQ,KAAK;aAGxB,SAAS,EAAE,MAAM;aACjB,QAAQ,EAAE,MAAM;gBAFhC,OAAO,EAAE,MAAM,EACC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM;CAKjC;AAED;;GAEG;AACH,qBAAa,iBAAiB;IAE5B,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,OAAO;gBADP,OAAO,EAAE,SAAS,EAClB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC;IAGzC;;;OAGG;IACH,IAAI,MAAM,IAAI,SAAS,CAEtB;IAED;;OAEG;IACG,OAAO,CAAC,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoB9E;;OAEG;IACG,QAAQ,CAAC,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA6B/E;;OAEG;IACG,SAAS,CAAC,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA4BhF;;OAEG;IACG,UAAU,CAAC,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA4BjF;;OAEG;IACH,kBAAkB,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI;CAShD"}
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../../src/lib/local-api/permissions.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAgB,MAAM,kBAAkB,CAAC;AACjE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAKjD,qBAAa,eAAgB,SAAQ,KAAK;aAGxB,SAAS,EAAE,MAAM;aACjB,QAAQ,EAAE,MAAM;gBAFhC,OAAO,EAAE,MAAM,EACC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM;CAKjC;AAmCD,qBAAa,iBAAiB;IAE5B,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,OAAO;gBADP,OAAO,EAAE,SAAS,EAClB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC;IAGzC,IAAI,MAAM,IAAI,SAAS,CAEtB;IAEK,OAAO,CAAC,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxF,SAAS,CAAC,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK1E,SAAS,CAAC,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhG;;;;OAIG;IACG,QAAQ,CAAC,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzF,SAAS,CAAC,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAI1F,UAAU,CACf,OAAO,EAAE,eAAe,EACxB,cAAc,EAAE,MAAM,EACtB,GAAG,CAAC,EAAE,QAAQ,GACZ,OAAO,CAAC,IAAI,CAAC;IAIV,YAAY,CACjB,OAAO,EAAE,eAAe,EACxB,cAAc,EAAE,MAAM,EACtB,GAAG,CAAC,EAAE,QAAQ,GACZ,OAAO,CAAC,IAAI,CAAC;IAIhB,kBAAkB,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI;YAYlC,MAAM;IAmBpB,OAAO,CAAC,SAAS;IAsBjB,OAAO,CAAC,WAAW;IAenB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,SAAS;CAmCjB"}

package/dist/local-api/permissions.js

@@ -1,9 +1,16 @@
 // local-api/permissions.ts
 //
-// Permission checking for the Local API layer
-/**
- * Permission error thrown when access is denied
- */
+// Permission checking for the Local API layer.
+//
+// Every operation resolves to a capability. A check passes when either:
+//   1. The collection schema declares `access[operation]` and the caller's
+//      effective organization role appears in the list, OR
+//   2. `auth.capabilities` (hydrated by the auth hook via RolesService)
+//      contains the capability.
+//
+// `overrideAccess` short-circuits everything for system operations.
+import { hasCapability, effectiveOrganizationRole } from '../types/capabilities.js';
+import { cmsLogger } from '../utils/logger.js';
 export class PermissionError extends Error {
     operation;
     resource;
@@ -14,9 +21,33 @@ export class PermissionError extends Error {
         this.name = 'PermissionError';
     }
 }
-/**
- * Checks permissions for Local API operations
- */
+const OPERATION_CAPABILITY = {
+    read: 'document.read',
+    create: 'document.create',
+    update: 'document.update',
+    delete: 'document.delete',
+    publish: 'document.publish',
+    unpublish: 'document.unpublish'
+};
+// Human-readable action phrasing for error messages. Keep in sync with
+// OPERATION_CAPABILITY and any new Operation keys.
+const OPERATION_LABEL = {
+    read: 'view',
+    create: 'create',
+    update: 'edit',
+    delete: 'delete',
+    publish: 'publish',
+    unpublish: 'unpublish'
+};
+function denialMessage(operations, collectionName) {
+    const actions = operations.map((op) => OPERATION_LABEL[op]);
+    const action = actions.length === 1
+        ? actions[0]
+        : actions.length === 2
+            ? `${actions[0]} or ${actions[1]}`
+            : `${actions.slice(0, -1).join(', ')}, or ${actions[actions.length - 1]}`;
+    return `You don't have permission to ${action} ${collectionName} documents. Ask an admin if you need access.`;
+}
 export class PermissionChecker {
     _config;
     schemas;
@@ -24,93 +55,104 @@ export class PermissionChecker {
         this._config = _config;
         this.schemas = schemas;
     }
-    /**
-     * Get the CMS config
-     * Available for future per-collection permission logic
-     */
     get config() {
         return this._config;
     }
-    /**
-     * Check if the current context has read permissions for a collection
-     */
-    async canRead(context, collectionName) {
-        // Always allow if overrideAccess is true (system operations)
-        if (context.overrideAccess) {
-            return;
-        }
-        // Require authentication for read operations
-        if (!context.user) {
-            throw new PermissionError('Authentication required for read operations', 'read', collectionName);
-        }
-        // All authenticated users can read (role-based restrictions handled by RLS)
-        // Additional per-collection permission logic can be added here in the future
-        return;
+    async canRead(context, collectionName, doc) {
+        await this.assert(context, collectionName, 'read', doc);
     }
-    /**
-     * Check if the current context has write permissions (create/update)
-     */
-    async canWrite(context, collectionName) {
-        // Always allow if overrideAccess is true (system operations)
-        if (context.overrideAccess) {
-            return;
-        }
-        // Require authentication for write operations
-        if (!context.user) {
-            throw new PermissionError('Authentication required for write operations', 'write', collectionName);
-        }
-        // Check if user has write role (not a viewer)
-        // Viewers have read-only access
-        if (context.user.role === 'viewer') {
-            throw new PermissionError('Write permission denied. Viewers have read-only access.', 'write', collectionName);
-        }
-        // Additional per-collection permission logic can be added here in the future
-        return;
+    async canCreate(context, collectionName) {
+        // `create` has no target doc by definition.
+        await this.assert(context, collectionName, 'create');
+    }
+    async canUpdate(context, collectionName, doc) {
+        await this.assert(context, collectionName, 'update', doc);
     }
     /**
-     * Check if the current context has delete permissions
+     * @deprecated Prefer `canCreate` or `canUpdate` — this method conflates the
+     * two and was only kept for legacy call sites. It now aliases `canUpdate`
+     * for safety (update is the more restrictive default for mutation).
      */
-    async canDelete(context, collectionName) {
-        // Always allow if overrideAccess is true (system operations)
-        if (context.overrideAccess) {
-            return;
-        }
-        // Require authentication for delete operations
-        if (!context.user) {
-            throw new PermissionError('Authentication required for delete operations', 'delete', collectionName);
-        }
-        // Viewers have read-only access
-        if (context.user.role === 'viewer') {
-            throw new PermissionError('Delete permission denied. Viewers have read-only access.', 'delete', collectionName);
+    async canWrite(context, collectionName, doc) {
+        await this.canUpdate(context, collectionName, doc);
+    }
+    async canDelete(context, collectionName, doc) {
+        await this.assert(context, collectionName, 'delete', doc);
+    }
+    async canPublish(context, collectionName, doc) {
+        await this.assert(context, collectionName, 'publish', doc);
+    }
+    async canUnpublish(context, collectionName, doc) {
+        await this.assert(context, collectionName, 'unpublish', doc);
+    }
+    validateCollection(collectionName) {
+        if (!this.schemas.has(collectionName)) {
+            throw new Error(`Collection "${collectionName}" not found in schema. Available collections: ${Array.from(this.schemas.keys()).join(', ')}`);
         }
-        // Additional per-collection permission logic can be added here in the future
-        return;
     }
-    /**
-     * Check if the current context has publish permissions
-     */
-    async canPublish(context, collectionName) {
-        // Always allow if overrideAccess is true (system operations)
-        if (context.overrideAccess) {
+    // ---- internals -----------------------------------------------------------
+    async assert(context, collectionName, operation, doc) {
+        if (context.overrideAccess)
             return;
+        const auth = this.requireAuth(context, operation, collectionName);
+        if (this.isAllowed(auth, collectionName, operation, doc))
+            return;
+        this.logDenial(auth, operation, collectionName, [OPERATION_CAPABILITY[operation]]);
+        throw new PermissionError(denialMessage([operation], collectionName), operation, collectionName);
+    }
+    logDenial(auth, operation, collectionName, missingCapabilities) {
+        const who = auth.type === 'session'
+            ? `user=${auth.user.id} role="${auth.organizationRole}"`
+            : auth.type === 'api_key'
+                ? `apiKey=${auth.keyId}`
+                : auth.type;
+        const caps = 'capabilities' in auth && Array.isArray(auth.capabilities)
+            ? auth.capabilities.join(',')
+            : '(none)';
+        cmsLogger.warn('[RBAC]', `DENY ${operation} on "${collectionName}" — ${who} has=[${caps}] needs=[${missingCapabilities.join('|')}]`);
+    }
+    requireAuth(context, operation, collectionName) {
+        if (!context.auth) {
+            throw new PermissionError(`You must be signed in to ${OPERATION_LABEL[operation]} ${collectionName} documents.`, operation, collectionName);
         }
-        // Require authentication for publish operations
-        if (!context.user) {
-            throw new PermissionError('Authentication required for publish operations', 'publish', collectionName);
-        }
-        // Check if user has write role (not a viewer)
-        if (context.user.role === 'viewer') {
-            throw new PermissionError('Publish permission denied. Viewers have read-only access.', 'publish', collectionName);
-        }
-        // Additional per-collection permission logic can be added here in the future
-        return;
+        return context.auth;
     }
     /**
-     * Validate that a collection exists in the schema
+     * Evaluate an access rule for a given operation.
+     *
+     * Three kinds of declared rules:
+     *   - `OrganizationRole[]` — role allowlist (as before).
+     *   - `(ctx) => boolean` — arbitrary policy, receives auth + optional doc.
+     *     Use for ownership rules like `doc.createdBy === auth.user.id`.
+     *   - `undefined` — fall back to capability check.
+     *
+     * A declared-but-excluded role/policy for a session caller is an explicit
+     * deny; the capability map does not re-grant access.
      */
-    validateCollection(collectionName) {
-        if (!this.schemas.has(collectionName)) {
-            throw new Error(`Collection "${collectionName}" not found in schema. Available collections: ${Array.from(this.schemas.keys()).join(', ')}`);
+    isAllowed(auth, collectionName, operation, doc) {
+        const schema = this.schemas.get(collectionName);
+        const declared = schema?.access?.[operation];
+        if (declared) {
+            if (typeof declared === 'function') {
+                try {
+                    return declared({ auth, doc });
+                }
+                catch (err) {
+                    // A throwing policy is a bug, not a grant — log and deny.
+                    cmsLogger.error('[RBAC]', `access policy for "${collectionName}.${operation}" threw:`, err);
+                    return false;
+                }
+            }
+            // Array-shaped rule (role allowlist)
+            const role = effectiveOrganizationRole(auth);
+            if (role && declared.includes(role))
+                return true;
+            if (auth.type === 'session' && role) {
+                return false;
+            }
+            // Unrecognized role (custom roles, API keys) → fall through to
+            // capability check so they can still gain access via capabilities.
         }
+        return hasCapability(auth, OPERATION_CAPABILITY[operation]);
     }
 }

package/dist/permissions-context.svelte.d.ts

@@ -0,0 +1,44 @@
+import type { Capability } from './types/capabilities.js';
+export interface PermissionsContext {
+    /** Current capability list (reactive). */
+    readonly capabilities: readonly string[];
+    /**
+     * Effective organization role name (reactive). `null` when the caller has
+     * no role (API key, unauthenticated). Used for role-name-based checks
+     * such as field-level access lists.
+     */
+    readonly role: string | null;
+    /** True if the session has the named capability. */
+    can(cap: Capability): boolean;
+    /** True if the session has at least one of the capabilities. */
+    canAny(...caps: Capability[]): boolean;
+    /** True if the session has every one of the capabilities. */
+    canAll(...caps: Capability[]): boolean;
+}
+/**
+ * Publish a capability context to descendants.
+ *
+ * `getCapabilities` is a getter rather than a static array so reactive
+ * sources (Svelte state, `$page.data.rbac.capabilities`) propagate: every
+ * `can()` call re-reads through the closure.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { page } from '$app/state';
+ *   import { setPermissionsContext } from '@aphexcms/cms-core';
+ *   setPermissionsContext(() => page.data.rbac?.capabilities ?? []);
+ * </script>
+ * ```
+ */
+export declare function setPermissionsContext(getCapabilities: () => readonly string[], getRole?: () => string | null): PermissionsContext;
+/**
+ * Read the capability context set by an ancestor.
+ *
+ * When no provider is present (e.g. a component rendered in isolation during
+ * tests or Storybook), returns a deny-all stub with a one-time dev warning
+ * rather than throwing — that way consumers degrade to "no affordances shown"
+ * instead of crashing the tree.
+ */
+export declare function usePermissions(): PermissionsContext;
+//# sourceMappingURL=permissions-context.svelte.d.ts.map

package/dist/permissions-context.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions-context.svelte.d.ts","sourceRoot":"","sources":["../src/lib/permissions-context.svelte.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAIvD,MAAM,WAAW,kBAAkB;IAClC,0CAA0C;IAC1C,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,oDAAoD;IACpD,GAAG,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC;IAC9B,gEAAgE;IAChE,MAAM,CAAC,GAAG,IAAI,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;IACvC,6DAA6D;IAC7D,MAAM,CAAC,GAAG,IAAI,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;CACvC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACpC,eAAe,EAAE,MAAM,SAAS,MAAM,EAAE,EACxC,OAAO,GAAE,MAAM,MAAM,GAAG,IAAiB,GACvC,kBAAkB,CAsBpB;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,IAAI,kBAAkB,CAKnD"}