@byline/core 4.15.0 → 4.17.0

package/dist/@types/db-types.d.ts

@@ -209,12 +209,16 @@ export interface IDbAdapter {
         counters: ICounterCommands;
         /** Append-only audit-log writes, committed atomically via `withTransaction`. */
         audit: IAuditCommands;
+        /** Singleton slot → document mapping writes. */
+        singletons: ISingletonCommands;
     };
     queries: {
         collections: ICollectionQueries;
         documents: IDocumentQueries;
         /** Audit-log reads — per-document history, system-wide report. */
         audit: IAuditQueries;
+        /** Singleton slot → document mapping reads. */
+        singletons: ISingletonQueries;
     };
     /**
      * Run `fn` inside a single database transaction so the
@@ -462,6 +466,50 @@ export interface ICollectionCommands {
     }): Promise<any>;
     delete(id: string): Promise<any>;
 }
+/**
+ * Writes to the singleton slot → document mapping
+ * (`byline_singleton_documents`). The mapping enforces slot and document
+ * uniqueness after the lifecycle caller has verified that the registered
+ * definition is a singleton. A singleton's identity must not depend on a
+ * document `path` (locale-bearing and re-anchorable) or on a well-known
+ * generated UUID.
+ *
+ * `setMapping` is called inside the same transaction as the document create it
+ * accompanies, so the content version and the mapping commit together.
+ */
+export interface ISingletonCommands {
+    /**
+     * Lock the singleton's registered collection row as the slot mutex.
+     * Callers must invoke this inside `IDbAdapter.withTransaction`; the row
+     * lock is then held until that ambient transaction commits or rolls back.
+     * Locking the registration row works before a mapping exists and behaves
+     * identically on every canonical adapter. Canonical adapters reject calls
+     * made without an ambient transaction instead of taking an autocommit lock
+     * that would be released before the caller's critical section.
+     */
+    lockSlot(collectionId: string): Promise<void>;
+    /**
+     * Record `documentId` as the singleton document for `collectionId`.
+     * The primary key on `collection_id` makes a competing concurrent insert
+     * fail rather than produce a second slot. This adapter primitive does not
+     * validate the registered collection kind; the singleton lifecycle must do
+     * that before calling it.
+     */
+    setMapping(collectionId: string, documentId: string): Promise<void>;
+    /**
+     * Remove the mapping. Not part of the public singleton API — the supported
+     * surface has no delete. Present for internal tooling and test cleanup.
+     */
+    clearMapping(collectionId: string): Promise<void>;
+}
+/** Reads of the singleton slot → document mapping. */
+export interface ISingletonQueries {
+    /**
+     * The mapped document id, or `null` when the slot has never been saved.
+     * `null` is the normal pre-materialisation state, not an error.
+     */
+    getMappedDocumentId(collectionId: string): Promise<string | null>;
+}
 /** Locked structural state returned by tree mutation commands. */
 export interface TreePlacementState {
     placed: boolean;
@@ -1040,6 +1088,8 @@ export interface IDocumentQueries {
     }): Promise<any | null>;
     getDocumentByVersion(params: {
         document_version_id: string;
+        /** Optional logical-document ownership gate for singleton historical reads. */
+        document_id?: string;
         locale?: string;
         /** Optional collection ownership gate for client-facing historical reads. */
         collection_id?: string;

package/dist/@types/form-admin-config.test.node.d.ts

@@ -0,0 +1,6 @@
+/**
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+export {};

package/dist/@types/form-admin-config.test.node.js

@@ -0,0 +1,26 @@
+/**
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+import { describe, expect, it } from 'vitest';
+describe('FormAdminConfig', () => {
+    it('accepts a config carrying only the form-facing keys', () => {
+        const config = {
+            fields: {},
+            tabSets: [],
+            rows: [],
+            groups: [],
+            layout: { main: [] },
+        };
+        expect(Object.keys(config).sort()).toEqual(['fields', 'groups', 'layout', 'rows', 'tabSets']);
+    });
+    it('is satisfied by a full CollectionAdminConfig', () => {
+        const collection = {
+            slug: 'pages',
+            layout: { main: [] },
+        };
+        const asForm = collection;
+        expect(asForm.layout).toEqual({ main: [] });
+    });
+});

package/dist/@types/singleton-admin-config.test.node.js

@@ -0,0 +1,66 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { describe, expect, it } from 'vitest';
+import { defineAdmin, defineSingletonAdmin } from './admin-types.js';
+import { defineCollection, defineSingleton } from './collection-types.js';
+const pages = defineCollection({
+    path: 'pages',
+    labels: { singular: 'Page', plural: 'Pages' },
+    fields: [{ name: 'title', label: 'Title', type: 'text' }],
+});
+const settings = defineSingleton({
+    path: 'site-settings',
+    label: 'Site settings',
+    fields: [{ name: 'title', label: 'Title', type: 'text' }],
+});
+describe('singleton admin config', () => {
+    it('stamps explicit resource-kind discriminants in both factories', () => {
+        const collectionAdmin = defineAdmin(pages, {});
+        const singletonAdmin = defineSingletonAdmin(settings, {});
+        expect(collectionAdmin.singleton).toBe(false);
+        expect(singletonAdmin.singleton).toBe(true);
+        expect(singletonAdmin.slug).toBe(settings.path);
+    });
+    it('does not let untyped config input override factory-owned identity', () => {
+        const collectionAdmin = defineAdmin(pages, {
+            singleton: true,
+            slug: 'wrong-collection',
+        });
+        const singletonAdmin = defineSingletonAdmin(settings, {
+            singleton: false,
+            slug: 'wrong-singleton',
+        });
+        expect(collectionAdmin).toMatchObject({ singleton: false, slug: pages.path });
+        expect(singletonAdmin).toMatchObject({ singleton: true, slug: settings.path });
+    });
+    it('shares the reusable form composition contract', () => {
+        const singletonAdmin = defineSingletonAdmin(settings, {
+            fields: { title: {} },
+            layout: { main: ['title'] },
+        });
+        const asForm = singletonAdmin;
+        expect(asForm.layout).toEqual({ main: ['title'] });
+    });
+    it('rejects collection-only admin options at the definition site', () => {
+        defineSingletonAdmin(settings, {
+            // @ts-expect-error — list columns have no meaning for a singleton resource.
+            columns: [{ fieldName: 'title', label: 'Title' }],
+        });
+    });
+    it('keeps the singleton preview document pathless', () => {
+        defineSingletonAdmin(settings, {
+            preview: {
+                url: (document) => {
+                    // @ts-expect-error — a singleton's internal generated path is never preview input.
+                    expect(document.path).toBeUndefined();
+                    return '/';
+                },
+            },
+        });
+    });
+});

package/dist/@types/singleton-definition.test.node.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export {};

package/dist/@types/singleton-definition.test.node.js

@@ -0,0 +1,75 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { describe, expect, it } from 'vitest';
+import { defineCollection, defineSingleton, isSingleton } from './collection-types.js';
+describe('defineSingleton', () => {
+    it('stamps the singleton discriminant', () => {
+        const def = defineSingleton({
+            path: 'site-settings',
+            label: 'Site settings',
+            fields: [{ name: 'name', label: 'Site name', type: 'text' }],
+        });
+        expect(def.singleton).toBe(true);
+        expect(def.path).toBe('site-settings');
+    });
+    it('narrows through isSingleton', () => {
+        const singleton = defineSingleton({
+            path: 'site-settings',
+            label: 'Site settings',
+            fields: [{ name: 'name', label: 'Site name', type: 'text' }],
+        });
+        const collection = defineCollection({
+            path: 'pages',
+            labels: { singular: 'Page', plural: 'Pages' },
+            fields: [{ name: 'title', label: 'Title', type: 'text' }],
+        });
+        expect(isSingleton(singleton)).toBe(true);
+        expect(isSingleton(collection)).toBe(false);
+    });
+    it('rejects a collection-only option at the definition site', () => {
+        defineSingleton({
+            path: 'site-settings',
+            label: 'Site settings',
+            // @ts-expect-error — `orderable` is `?: never` on SingletonDefinition.
+            // The directive suppresses only the NEXT line, so it must sit here and
+            // not above `defineSingleton(`. If it ever stops erroring, the union has
+            // gone soft and runtime validation is all that is left.
+            orderable: true,
+            fields: [{ name: 'name', label: 'Site name', type: 'text' }],
+        });
+    });
+    it('keeps collection and singleton hook families disjoint at the definition site', () => {
+        defineSingleton({
+            path: 'site-settings',
+            label: 'Site settings',
+            fields: [{ name: 'name', label: 'Site name', type: 'text' }],
+            hooks: {
+                // @ts-expect-error — collection create hooks do not exist on a singleton.
+                beforeCreate: () => { },
+            },
+        });
+        defineCollection({
+            path: 'pages',
+            labels: { singular: 'Page', plural: 'Pages' },
+            fields: [{ name: 'title', label: 'Title', type: 'text' }],
+            hooks: {
+                // @ts-expect-error — singleton save hooks do not exist on a collection.
+                beforeSave: () => { },
+            },
+        });
+    });
+    it('preserves literal path types for the generated registries', () => {
+        const def = defineSingleton({
+            path: 'site-settings',
+            label: 'Site settings',
+            fields: [{ name: 'name', label: 'Site name', type: 'text' }],
+        });
+        const path = def.path;
+        expect(path).toBe('site-settings');
+    });
+});

package/dist/@types/site-config.d.ts

@@ -9,8 +9,8 @@ import type { SessionProvider } from '@byline/auth';
 import type { RecurringTaskDefinition } from '../scheduler/types.js';
 import type { SlugifierFn } from '../utils/slugify.js';
 import type { FilenameSlugifierFn } from '../utils/slugify-filename.js';
-import type { BlockAdminConfig, CollectionAdminConfig, CollectionGroupDefinition } from './admin-types.js';
-import type { CollectionDefinition, CollectionHooks, CollectionHooksLoader, UploadHooks, UploadHooksLoader } from './collection-types.js';
+import type { AdminResourceConfig, BlockAdminConfig, CollectionGroupDefinition } from './admin-types.js';
+import type { CollectionDefinition, CollectionHooks, CollectionHooksLoader, SingletonHooks, SingletonHooksLoader, UploadHooks, UploadHooksLoader } from './collection-types.js';
 import type { IDbAdapter } from './db-types.js';
 import type { RichTextEditorComponent, RichTextEmbedFn, RichTextPopulateFn, RichTextToMarkdownFn, RichTextToTextFn } from './field-types.js';
 import type { SearchProvider } from './search-types.js';
@@ -145,12 +145,13 @@ export type TranslationBundleShape = Readonly<{
  * Used by `defineAdminConfig()` and consumed by admin UI routes.
  */
 export interface AdminConfig extends BaseConfig {
-    /** Admin UI configuration for collections (client-side only). */
-    admin?: CollectionAdminConfig[];
+    /** Admin UI configuration for collections and singleton resources (client-side only). */
+    admin?: AdminResourceConfig[];
     /**
-     * Ordered registry of dashboard collection groups. Array order is display
-     * order. A collection joins a group by setting `CollectionAdminConfig.group`
-     * to an entry's `name`.
+     * Ordered registry of dashboard resource groups. Array order is display
+     * order. A collection or singleton joins a group through its admin config's
+     * `group` property. The property name remains `collectionGroups` for
+     * backwards compatibility.
      *
      * Omit entirely to keep the flat, ungrouped dashboard grid — this property is
      * purely additive and changes nothing when absent.
@@ -239,7 +240,7 @@ export type ResolvedAdminConfig = Omit<AdminConfig, 'routes'> & {
  * ```
  */
 export interface ServerHooksConfig {
-    collections?: Record<string, CollectionHooks | CollectionHooksLoader>;
+    collections?: Record<string, CollectionHooks | CollectionHooksLoader | SingletonHooks | SingletonHooksLoader>;
     uploads?: Record<string, UploadHooks | UploadHooksLoader>;
 }
 /** Installation-wide switch for Byline's scheduled-publication subsystem. */

package/dist/auth/apply-before-read.d.ts

@@ -14,7 +14,8 @@ import type { QueryPredicate } from '../@types/query-predicate.js';
  * Resolve the per-collection `beforeRead` hook predicate for the current
  * request, with caching across populate fanout.
  *
- * Each configured hook function runs in declaration order. Predicates from
+ * Each configured hook function runs in declaration order. `false` is
+ * normalized to the documented always-false predicate, and predicates from
  * multiple hooks are combined with implicit AND. Results are cached in
  * module-private state bound to one request authority; caller-owned
  * `ReadContext` properties are never consulted for authorization.

package/dist/auth/apply-before-read.js

@@ -14,7 +14,8 @@ const readSecurityStates = new WeakMap();
  * Resolve the per-collection `beforeRead` hook predicate for the current
  * request, with caching across populate fanout.
  *
- * Each configured hook function runs in declaration order. Predicates from
+ * Each configured hook function runs in declaration order. `false` is
+ * normalized to the documented always-false predicate, and predicates from
  * multiple hooks are combined with implicit AND. Results are cached in
  * module-private state bound to one request authority; caller-owned
  * `ReadContext` properties are never consulted for authorization.
@@ -48,8 +49,9 @@ export async function applyBeforeRead(params) {
                 requestContext,
                 readContext: createHookReadContext(scope, entry),
             });
-            if (result != null)
-                predicates.push(result);
+            const predicate = normalizeBeforeReadResult(result);
+            if (predicate !== undefined)
+                predicates.push(predicate);
         }
         if (predicates.length === 0)
             return null;
@@ -173,3 +175,11 @@ function normalizeBeforeReadHook(slot) {
         return [];
     return Array.isArray(slot) ? slot : [slot];
 }
+/** Normalize the deny-all shorthand without teaching the predicate parser a sentinel value. */
+function normalizeBeforeReadResult(result) {
+    if (result === false)
+        return { id: { $in: [] } };
+    if (result === undefined)
+        return undefined;
+    return result;
+}

package/dist/auth/apply-before-read.test.node.js

@@ -48,6 +48,50 @@ describe('applyBeforeRead', () => {
         });
         expect(result).toBeNull();
     });
+    it('normalizes false to the documented always-false predicate', async () => {
+        const hook = () => false;
+        const result = await applyBeforeRead({
+            definition: baseCollection(hook),
+            requestContext: createRequestContext(),
+            readContext: createReadContext(),
+        });
+        expect(result).toEqual({ id: { $in: [] } });
+    });
+    it('normalizes an async false result identically', async () => {
+        const hook = async () => {
+            await Promise.resolve();
+            return false;
+        };
+        const result = await applyBeforeRead({
+            definition: baseCollection(hook),
+            requestContext: createRequestContext(),
+            readContext: createReadContext(),
+        });
+        expect(result).toEqual({ id: { $in: [] } });
+    });
+    it('keeps false restrictive in either hook order', async () => {
+        const deny = () => false;
+        const permit = () => ({ status: 'published' });
+        const params = {
+            requestContext: createRequestContext(),
+            readContext: createReadContext(),
+        };
+        await expect(applyBeforeRead({ ...params, definition: baseCollection([deny, permit]) })).resolves.toEqual({
+            $and: [{ id: { $in: [] } }, { status: 'published' }],
+        });
+        await expect(applyBeforeRead({
+            ...params,
+            definition: baseCollection([permit, deny]),
+            readContext: createReadContext(),
+        })).resolves.toEqual({
+            $and: [{ status: 'published' }, { id: { $in: [] } }],
+        });
+    });
+    it('does not admit true as an affirmative-allow result', () => {
+        // @ts-expect-error true is deliberately outside the beforeRead contract
+        const hook = () => true;
+        expect(hook).toBeTypeOf('function');
+    });
     it('combines multiple hook predicates with implicit AND', async () => {
         const a = () => ({ tenantId: 't-1' });
         const b = () => ({ status: 'published' });

package/dist/auth/assert-actor-can-perform.d.ts

@@ -6,7 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 import { type RequestContext } from '@byline/auth';
-import { type CollectionAbilityVerb } from './register-collection-abilities.js';
+import { type DocumentAbilityResource, type DocumentAbilityVerbFor } from './register-collection-abilities.js';
 /**
  * Central enforcement helper. Called from the service layer — at the top
  * of each `document-lifecycle` function and at the top of each
@@ -25,7 +25,8 @@ import { type CollectionAbilityVerb } from './register-collection-abilities.js';
  *          default for unauthenticated consumers).
  *        - Any other combination → `ERR_UNAUTHENTICATED`.
  *
- *   3. **Actor present** → `actor.assertAbility('collections.<path>.<verb>')`.
+ *   3. **Actor present** → assert the kind-aware ability key derived from the
+ *      resource descriptor.
  *      `AdminAuth` with `isSuperAdmin: true` short-circuits the check
  *      internally; any other actor must hold the specific ability.
  *
@@ -35,4 +36,4 @@ import { type CollectionAbilityVerb } from './register-collection-abilities.js';
  *
  * See docs/07-auth-and-security/01-authn-authz.md.
  */
-export declare function assertActorCanPerform(context: RequestContext | undefined, collectionPath: string, verb: CollectionAbilityVerb): void;
+export declare function assertActorCanPerform<Resource extends DocumentAbilityResource>(context: RequestContext | undefined, resource: Resource, verb: DocumentAbilityVerbFor<Resource>): void;

package/dist/auth/assert-actor-can-perform.js

@@ -6,7 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 import { ERR_UNAUTHENTICATED } from '@byline/auth';
-import { collectionAbilityKey, } from './register-collection-abilities.js';
+import { documentAbilityKey, } from './register-collection-abilities.js';
 /**
  * Central enforcement helper. Called from the service layer — at the top
  * of each `document-lifecycle` function and at the top of each
@@ -25,7 +25,8 @@ import { collectionAbilityKey, } from './register-collection-abilities.js';
  *          default for unauthenticated consumers).
  *        - Any other combination → `ERR_UNAUTHENTICATED`.
  *
- *   3. **Actor present** → `actor.assertAbility('collections.<path>.<verb>')`.
+ *   3. **Actor present** → assert the kind-aware ability key derived from the
+ *      resource descriptor.
  *      `AdminAuth` with `isSuperAdmin: true` short-circuits the check
  *      internally; any other actor must hold the specific ability.
  *
@@ -35,10 +36,11 @@ import { collectionAbilityKey, } from './register-collection-abilities.js';
  *
  * See docs/07-auth-and-security/01-authn-authz.md.
  */
-export function assertActorCanPerform(context, collectionPath, verb) {
+export function assertActorCanPerform(context, resource, verb) {
+    const path = resource.path;
     if (!context) {
         throw ERR_UNAUTHENTICATED({
-            message: `missing requestContext on ${verb} '${collectionPath}'. Pass createSuperAdminContext() ` +
+            message: `missing requestContext on ${verb} '${path}'. Pass createSuperAdminContext() ` +
                 `from @byline/auth for scripts/tests, or construct a request-scoped context from your ` +
                 `session provider in the admin webapp.`,
         });
@@ -47,17 +49,17 @@ export function assertActorCanPerform(context, collectionPath, verb) {
     if (actor == null) {
         if (verb !== 'read') {
             throw ERR_UNAUTHENTICATED({
-                message: `anonymous request cannot ${verb} '${collectionPath}': no actor in context`,
+                message: `anonymous request cannot ${verb} '${path}': no actor in context`,
             });
         }
         if (readMode !== 'published') {
             throw ERR_UNAUTHENTICATED({
-                message: `anonymous read of '${collectionPath}' requires readMode: 'published' ` +
+                message: `anonymous read of '${path}' requires readMode: 'published' ` +
                     `(got readMode: ${readMode == null ? '<unset>' : `'${readMode}'`})`,
             });
         }
         // Anonymous read of published content — permitted.
         return;
     }
-    actor.assertAbility(collectionAbilityKey(collectionPath, verb));
+    actor.assertAbility(documentAbilityKey(resource, verb));
 }

package/dist/auth/assert-actor-can-perform.test.node.js

@@ -8,11 +8,14 @@
 import { AdminAuth, AuthError, AuthErrorCodes, createRequestContext, createSuperAdminContext, } from '@byline/auth';
 import { describe, expect, it } from 'vitest';
 import { assertActorCanPerform } from './assert-actor-can-perform.js';
+const pages = { kind: 'collection', path: 'pages' };
+const news = { kind: 'collection', path: 'news' };
+const siteSettings = { kind: 'singleton', path: 'site-settings' };
 describe('assertActorCanPerform', () => {
     describe('missing context', () => {
         it('throws ERR_UNAUTHENTICATED when context is undefined', () => {
             try {
-                assertActorCanPerform(undefined, 'pages', 'read');
+                assertActorCanPerform(undefined, pages, 'read');
                 expect.fail('expected ERR_UNAUTHENTICATED');
             }
             catch (err) {
@@ -24,12 +27,13 @@ describe('assertActorCanPerform', () => {
     describe('null actor (anonymous)', () => {
         it('permits read with readMode: published', () => {
             const ctx = createRequestContext({ actor: null, readMode: 'published' });
-            expect(() => assertActorCanPerform(ctx, 'pages', 'read')).not.toThrow();
+            expect(() => assertActorCanPerform(ctx, pages, 'read')).not.toThrow();
+            expect(() => assertActorCanPerform(ctx, siteSettings, 'read')).not.toThrow();
         });
         it('rejects read with readMode: any', () => {
             const ctx = createRequestContext({ actor: null, readMode: 'any' });
             try {
-                assertActorCanPerform(ctx, 'pages', 'read');
+                assertActorCanPerform(ctx, pages, 'read');
                 expect.fail('expected ERR_UNAUTHENTICATED');
             }
             catch (err) {
@@ -40,7 +44,7 @@ describe('assertActorCanPerform', () => {
         it('rejects read when readMode is unset', () => {
             const ctx = createRequestContext({ actor: null });
             try {
-                assertActorCanPerform(ctx, 'pages', 'read');
+                assertActorCanPerform(ctx, pages, 'read');
                 expect.fail('expected ERR_UNAUTHENTICATED');
             }
             catch (err) {
@@ -51,7 +55,7 @@ describe('assertActorCanPerform', () => {
             const ctx = createRequestContext({ actor: null, readMode: 'published' });
             for (const verb of ['create', 'update', 'delete', 'publish', 'changeStatus']) {
                 try {
-                    assertActorCanPerform(ctx, 'pages', verb);
+                    assertActorCanPerform(ctx, pages, verb);
                     expect.fail(`expected ERR_UNAUTHENTICATED for ${verb}`);
                 }
                 catch (err) {
@@ -67,7 +71,7 @@ describe('assertActorCanPerform', () => {
                 abilities: ['collections.pages.update'],
             });
             const ctx = createRequestContext({ actor });
-            expect(() => assertActorCanPerform(ctx, 'pages', 'update')).not.toThrow();
+            expect(() => assertActorCanPerform(ctx, pages, 'update')).not.toThrow();
         });
         it('throws ERR_FORBIDDEN when the specific ability is missing', () => {
             const actor = new AdminAuth({
@@ -76,7 +80,7 @@ describe('assertActorCanPerform', () => {
             });
             const ctx = createRequestContext({ actor });
             try {
-                assertActorCanPerform(ctx, 'pages', 'publish');
+                assertActorCanPerform(ctx, pages, 'publish');
                 expect.fail('expected ERR_FORBIDDEN');
             }
             catch (err) {
@@ -90,9 +94,9 @@ describe('assertActorCanPerform', () => {
                 abilities: ['collections.pages.update'], // has update for 'pages' only
             });
             const ctx = createRequestContext({ actor });
-            expect(() => assertActorCanPerform(ctx, 'pages', 'update')).not.toThrow();
+            expect(() => assertActorCanPerform(ctx, pages, 'update')).not.toThrow();
             try {
-                assertActorCanPerform(ctx, 'news', 'update');
+                assertActorCanPerform(ctx, news, 'update');
                 expect.fail('expected ERR_FORBIDDEN — wrong collection');
             }
             catch (err) {
@@ -100,6 +104,19 @@ describe('assertActorCanPerform', () => {
                 expect(err.message).toContain('collections.news.update');
             }
         });
+        it('keeps collection and singleton namespaces isolated', () => {
+            const singletonActor = new AdminAuth({
+                id: 'singleton-editor',
+                abilities: ['singletons.site-settings.update'],
+            });
+            expect(() => assertActorCanPerform(createRequestContext({ actor: singletonActor }), siteSettings, 'update')).not.toThrow();
+            const collectionActor = new AdminAuth({
+                id: 'editor-1',
+                abilities: ['collections.site-settings.update'],
+            });
+            const ctx = createRequestContext({ actor: collectionActor });
+            expect(() => assertActorCanPerform(ctx, siteSettings, 'update')).toThrow(/singletons\.site-settings\.update/);
+        });
     });
     describe('super-admin', () => {
         it('passes every verb on every collection without explicit abilities', () => {
@@ -114,13 +131,17 @@ describe('assertActorCanPerform', () => {
                 'reindex',
             ];
             for (const verb of verbs) {
-                expect(() => assertActorCanPerform(ctx, 'any-collection', verb)).not.toThrow();
+                expect(() => assertActorCanPerform(ctx, { kind: 'collection', path: 'any-collection' }, verb)).not.toThrow();
             }
         });
         it('passes even when readMode would normally reject a null actor', () => {
             // Super-admin doesn't care about readMode at this layer.
             const ctx = createSuperAdminContext();
-            expect(() => assertActorCanPerform(ctx, 'pages', 'read')).not.toThrow();
+            expect(() => assertActorCanPerform(ctx, pages, 'read')).not.toThrow();
         });
     });
+    it('rejects anonymous singleton updates', () => {
+        const ctx = createRequestContext({ actor: null, readMode: 'published' });
+        expect(() => assertActorCanPerform(ctx, siteSettings, 'update')).toThrowError(expect.objectContaining({ code: AuthErrorCodes.UNAUTHENTICATED }));
+    });
 });

package/dist/auth/filter-readable-collections.d.ts

@@ -17,14 +17,14 @@ export interface ActorAbilitySnapshot {
     abilities: readonly string[];
 }
 /**
- * Narrow a collection list to those the administrator can read.
+ * Narrow a document-resource list to those the administrator can read.
  *
  * `read` is the gate because everything a dashboard card offers — the link to
- * the list view, and the per-status counts — requires
- * `collections.<path>.read` and is rejected server-side without it. An
- * administrator who cannot read a collection would otherwise see a card whose
- * status tiles all read zero, which is indistinguishable from a collection that
- * is genuinely empty.
+ * its editor/list view, and collection status counts — requires the resource's
+ * kind-aware `collections.<path>.read` or `singletons.<path>.read` ability and
+ * is rejected server-side without it. An administrator who cannot read a
+ * collection would otherwise see a card whose status tiles all read zero,
+ * which is indistinguishable from a collection that is genuinely empty.
  *
  * **Cosmetic only.** This is an affordance, never a security boundary.
  * `assertActorCanPerform` remains the enforcement point on every read and write

package/dist/auth/filter-readable-collections.js

@@ -5,16 +5,16 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import { collectionAbilityKey } from './register-collection-abilities.js';
+import { documentAbilityKey } from './register-collection-abilities.js';
 /**
- * Narrow a collection list to those the administrator can read.
+ * Narrow a document-resource list to those the administrator can read.
  *
  * `read` is the gate because everything a dashboard card offers — the link to
- * the list view, and the per-status counts — requires
- * `collections.<path>.read` and is rejected server-side without it. An
- * administrator who cannot read a collection would otherwise see a card whose
- * status tiles all read zero, which is indistinguishable from a collection that
- * is genuinely empty.
+ * its editor/list view, and collection status counts — requires the resource's
+ * kind-aware `collections.<path>.read` or `singletons.<path>.read` ability and
+ * is rejected server-side without it. An administrator who cannot read a
+ * collection would otherwise see a card whose status tiles all read zero,
+ * which is indistinguishable from a collection that is genuinely empty.
  *
  * **Cosmetic only.** This is an affordance, never a security boundary.
  * `assertActorCanPerform` remains the enforcement point on every read and write
@@ -28,5 +28,5 @@ export function filterReadableCollections(collections, snapshot) {
     if (snapshot.isSuperAdmin)
         return [...collections];
     const held = new Set(snapshot.abilities);
-    return collections.filter((collection) => held.has(collectionAbilityKey(collection.path, 'read')));
+    return collections.filter((collection) => held.has(documentAbilityKey(collection, 'read')));
 }