@byline/core 3.20.4 → 4.0.0

package/dist/@types/query-predicate.d.ts

@@ -76,9 +76,9 @@ export type PredicateValue = string | number | boolean | null | FilterOperators
  * }
  * ```
  *
- * Returning `undefined` from `beforeRead` means "no scoping". Use a
- * sentinel predicate that yields no rows (e.g. `{ id: '__none__' }`)
- * rather than throwing when the actor can read nothing — empty results
+ * Returning `undefined` from `beforeRead` means "no scoping". Use
+ * `{ id: { $in: [] } }` as the always-false predicate rather than an invalid
+ * UUID sentinel or an exception when the actor can read nothing. Empty results
  * are the correct shape for list endpoints.
  */
 export interface QueryPredicate {

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

@@ -0,0 +1,38 @@
+/**
+ * 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
+ */
+/** The persisted, unpopulated value of a relation field. */
+export interface RelatedDocumentValue {
+    targetDocumentId: string;
+    targetCollectionId: string;
+    relationshipType?: string;
+    cascadeDelete?: boolean;
+}
+/** A relation value that has not passed through population. */
+export interface UnpopulatedRelationValue extends RelatedDocumentValue {
+    _resolved?: never;
+    _cycle?: never;
+    document?: never;
+}
+/** Marker used when the target was already materialised in this read request. */
+export interface CycleRelationValue extends RelatedDocumentValue {
+    _resolved: true;
+    _cycle: true;
+}
+/** Marker used when the referenced target could not be read. */
+export interface UnresolvedRelationValue extends RelatedDocumentValue {
+    _resolved: false;
+}
+/** Relation envelope used when population successfully resolves the target. */
+export interface PopulatedRelationValue<TDocument = Record<string, any>> extends RelatedDocumentValue {
+    _resolved: true;
+    document: TDocument;
+}
+/** Every relation shape that can occur on the read path. */
+export type RelationReadValue<TDocument = Record<string, any>> = UnpopulatedRelationValue | PopulatedRelationValue<TDocument> | UnresolvedRelationValue | CycleRelationValue;
+/** Read shape for a single-target or `hasMany` relation field. */
+export type RelationFieldReadValue<HasMany extends boolean, TDocument = Record<string, any>> = HasMany extends true ? RelationReadValue<TDocument>[] : RelationReadValue<TDocument>;

package/dist/@types/relation-types.js

@@ -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/search-types.d.ts

@@ -203,10 +203,9 @@ export interface SearchResults {
     /**
      * Total matches across all pages (not just the returned `hits`).
      *
-     * This is the *provider's* count. When the querying collection applies
-     * `beforeRead` row scoping, unauthorized hits are dropped **after**
-     * ranking (see `CollectionHandle.search`), so `total` — like facet
-     * counts — is approximate under scoping and exact without it.
+     * This is the provider-level count. Client authorization layers must not
+     * expose it when collections or rows are removed after ranking; they return
+     * a conservative authorized page count instead.
      */
     total: number;
     /**

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

@@ -8,7 +8,7 @@
 import type { SessionProvider } from '@byline/auth';
 import type { SlugifierFn } from '../utils/slugify.js';
 import type { CollectionAdminConfig } from './admin-types.js';
-import type { CollectionDefinition } from './collection-types.js';
+import type { CollectionDefinition, CollectionHooks, CollectionHooksLoader, 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';
@@ -17,14 +17,19 @@ export type DbAdapterFn = (args: {
     connectionString: string;
 }) => IDbAdapter;
 /**
- * URL path segments for the admin and (future) public API routes.
- * Both values are optional on the input side — callers typically read the
- * resolved shape via `resolveRoutes()` which fills in `'/admin'` and `'/api'`
- * defaults.
+ * Resolved client-safe URL paths for Byline-owned routes. All paths may contain
+ * multiple segments when their route trees remain separate.
  */
 export interface RoutesConfig {
-    admin: string;
-    api: string;
+    readonly admin: string;
+    readonly api: string;
+    readonly signIn: string;
+}
+/** Partial route values accepted at configuration boundaries. */
+export interface RoutesConfigInput {
+    admin?: string;
+    api?: string;
+    signIn?: string;
 }
 /**
  * Common configuration shared by the server and client. Contains only
@@ -113,14 +118,12 @@ export interface BaseConfig {
          */
         translations?: TranslationBundleShape;
     };
-    collections: CollectionDefinition[];
+    collections: readonly CollectionDefinition[];
     /**
-     * URL segments for admin and API routes. Both keys default to `/admin`
-     * and `/api` respectively — installations only set this when they want
-     * to mount the admin or API at a non-default path. Consumers should
-     * read these via `resolveRoutes()` so the defaults are always applied.
+     * Client-safe admin, API, and sign-in route input. Registration applies
+     * defaults and canonicalization before exposing the config to consumers.
      */
-    routes?: Partial<RoutesConfig>;
+    routes?: RoutesConfigInput;
 }
 /**
  * Inline structural shape for the admin translation registry. Kept here
@@ -190,6 +193,31 @@ export interface ClientConfig extends BaseConfig {
         };
     };
 }
+/** Client config returned after boundary validation and canonicalization. */
+export type ResolvedClientConfig = Omit<ClientConfig, 'routes'> & {
+    routes: RoutesConfig;
+};
+/**
+ * Server-only lifecycle hook registry. Collection keys are collection paths;
+ * upload keys are `<collectionPath>.<canonical schema path>`. Canonical upload
+ * paths contain field names without runtime array indexes, and include a block
+ * type segment immediately after a blocks field.
+ *
+ * @example
+ * ```ts
+ * hooks: {
+ *   collections: { docs: () => import('./collections/docs/hooks.js') },
+ *   uploads: {
+ *     'documents.files.filesGroup.publicationFile': () => import('./collections/files/hooks.js'),
+ *     'pages.content.hero.backgroundImage': () => import('./collections/pages/hero-hooks.js'),
+ *   },
+ * }
+ * ```
+ */
+export interface ServerHooksConfig {
+    collections?: Record<string, CollectionHooks | CollectionHooksLoader>;
+    uploads?: Record<string, UploadHooks | UploadHooksLoader>;
+}
 /**
  * Server-side configuration. Extends BaseConfig with database and storage
  * adapters. Deliberately does NOT extend ClientConfig — the server has no
@@ -204,6 +232,13 @@ export interface ClientConfig extends BaseConfig {
  */
 export interface ServerConfig<TAdminStore = unknown> extends BaseConfig {
     db: IDbAdapter;
+    /**
+     * Server-only collection and upload hooks, attached to schema definitions
+     * after initialization succeeds. Prefer this registry when hook modules
+     * import server-only code; portable schema modules stay host-agnostic and
+     * client-safe.
+     */
+    hooks?: ServerHooksConfig;
     /**
      * Site-wide default storage provider for upload-capable image/file
      * fields.
@@ -370,3 +405,7 @@ export interface ServerConfig<TAdminStore = unknown> extends BaseConfig {
      */
     search?: SearchProvider;
 }
+/** Server config returned after boundary validation and canonicalization. */
+export type ResolvedServerConfig<TAdminStore = unknown> = Omit<ServerConfig<TAdminStore>, 'routes'> & {
+    routes: RoutesConfig;
+};

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

@@ -7,22 +7,17 @@
  */
 import type { RequestContext } from '@byline/auth';
 import { type CollectionDefinition } from '../@types/collection-types.js';
-import type { ReadContext } from '../@types/db-types.js';
+import { type ParseContext } from '../query/parse-where.js';
+import type { DocumentFilter, ReadContext } from '../@types/db-types.js';
 import type { QueryPredicate } from '../@types/query-predicate.js';
 /**
  * Resolve the per-collection `beforeRead` hook predicate for the current
  * request, with caching across populate fanout.
  *
- * Behaviour:
- *   - Cache hit on `readContext.beforeReadCache` (keyed by collection
- *     path) returns the cached value immediately. The actor is invariant
- *     for the lifetime of one `ReadContext`, so a single key per
- *     collection is sufficient.
- *   - Each configured hook function runs in declaration order. Predicates
- *     returned by multiple hooks are combined with implicit AND. Hooks
- *     that return `void` / `undefined` are skipped.
- *   - The result is stored in the cache (including `null` for "ran with
- *     no scoping") so subsequent batches in the same request reuse it.
+ * Each configured hook function runs in declaration order. 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.
  *
  * Returns `null` when no hook is configured, or every hook returned
  * void. Callers (`CollectionHandle`, `populateDocuments`) treat `null`
@@ -32,4 +27,21 @@ export declare function applyBeforeRead(params: {
     definition: CollectionDefinition;
     requestContext: RequestContext;
     readContext: ReadContext;
+    /** Stable adapter/client identity. Defaults to the definition for direct callers. */
+    securityDomain?: object;
 }): Promise<QueryPredicate | null>;
+/**
+ * Resolve and strictly compile the security predicate once per logical read.
+ * Promise caching also prevents concurrent populate branches from compiling
+ * the same predicate or resolving its relation collection ids more than once.
+ */
+export declare function compileBeforeReadFilters(params: {
+    definition: CollectionDefinition;
+    requestContext: RequestContext;
+    readContext: ReadContext;
+    parseContext: ParseContext;
+    /** Stable identity shared by every fanout path using this adapter/client. */
+    securityDomain: object;
+}): Promise<DocumentFilter[] | undefined>;
+/** Bind a logical read to one immutable request authority. */
+export declare function bindReadContextAuthority(readContext: ReadContext, requestContext: RequestContext): void;

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

@@ -6,60 +6,166 @@
  * Copyright (c) Infonomic Company Limited
  */
 import { resolveHooks, } from '../@types/collection-types.js';
+import { ERR_READ_RECURSION, ERR_VALIDATION } from '../lib/errors.js';
+import { parsePredicateFilters } from '../query/parse-where.js';
+import { createHookReadContext, getReadContextScope } from './read-context-scope.js';
+const readSecurityStates = new WeakMap();
 /**
  * Resolve the per-collection `beforeRead` hook predicate for the current
  * request, with caching across populate fanout.
  *
- * Behaviour:
- *   - Cache hit on `readContext.beforeReadCache` (keyed by collection
- *     path) returns the cached value immediately. The actor is invariant
- *     for the lifetime of one `ReadContext`, so a single key per
- *     collection is sufficient.
- *   - Each configured hook function runs in declaration order. Predicates
- *     returned by multiple hooks are combined with implicit AND. Hooks
- *     that return `void` / `undefined` are skipped.
- *   - The result is stored in the cache (including `null` for "ran with
- *     no scoping") so subsequent batches in the same request reuse it.
+ * Each configured hook function runs in declaration order. 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.
  *
  * Returns `null` when no hook is configured, or every hook returned
  * void. Callers (`CollectionHandle`, `populateDocuments`) treat `null`
  * the same as "no scoping" — they pass nothing extra to the adapter.
  */
 export async function applyBeforeRead(params) {
-    const { definition, requestContext, readContext } = params;
+    const { definition, requestContext, readContext, securityDomain = definition } = params;
     const collectionPath = definition.path;
-    if (readContext.beforeReadCache.has(collectionPath)) {
-        return readContext.beforeReadCache.get(collectionPath) ?? null;
+    const scope = getReadContextScope(readContext);
+    const entry = getBeforeReadCacheEntry(scope.root, requestContext, securityDomain, definition);
+    if (scope.ancestry.includes(entry)) {
+        throw ERR_READ_RECURSION({
+            message: `beforeRead recursion blocked for collection '${collectionPath}'`,
+            details: { collectionPath, readMode: requestContext.readMode ?? 'any' },
+        });
     }
-    const resolved = await resolveHooks(definition);
-    const hooks = normalizeBeforeReadHook(resolved?.beforeRead);
-    if (hooks.length === 0) {
-        readContext.beforeReadCache.set(collectionPath, null);
-        return null;
+    if (entry.predicate)
+        return entry.predicate;
+    const pending = (async () => {
+        const resolved = await resolveHooks(definition);
+        const hooks = normalizeBeforeReadHook(resolved?.beforeRead);
+        if (hooks.length === 0)
+            return null;
+        const predicates = [];
+        for (const hook of hooks) {
+            const result = await hook({
+                collectionPath,
+                requestContext,
+                readContext: createHookReadContext(scope, entry),
+            });
+            if (result != null)
+                predicates.push(result);
+        }
+        if (predicates.length === 0)
+            return null;
+        if (predicates.length === 1)
+            return predicates[0] ?? null;
+        return { $and: predicates };
+    })();
+    entry.predicate = pending;
+    return pending;
+}
+/**
+ * Resolve and strictly compile the security predicate once per logical read.
+ * Promise caching also prevents concurrent populate branches from compiling
+ * the same predicate or resolving its relation collection ids more than once.
+ */
+export async function compileBeforeReadFilters(params) {
+    const { definition, requestContext, readContext, parseContext, securityDomain } = params;
+    const scope = getReadContextScope(readContext);
+    const entry = getBeforeReadCacheEntry(scope.root, requestContext, securityDomain, definition);
+    if (scope.ancestry.includes(entry)) {
+        throw ERR_READ_RECURSION({
+            message: `beforeRead recursion blocked for collection '${definition.path}'`,
+            details: {
+                collectionPath: definition.path,
+                readMode: requestContext.readMode ?? 'any',
+            },
+        });
     }
-    const predicates = [];
-    for (const hook of hooks) {
-        const result = await hook({
-            collectionPath,
+    if (entry.compiledFilters)
+        return entry.compiledFilters;
+    const compiled = (async () => {
+        const predicate = await applyBeforeRead({
+            definition,
             requestContext,
             readContext,
+            securityDomain,
+        });
+        if (predicate == null)
+            return undefined;
+        const filters = await parsePredicateFilters(predicate, definition, parseContext, {
+            strict: true,
         });
-        if (result != null) {
-            predicates.push(result);
+        return filters.length > 0 ? filters : undefined;
+    })();
+    entry.compiledFilters = compiled;
+    return compiled;
+}
+/** Bind a logical read to one immutable request authority. */
+export function bindReadContextAuthority(readContext, requestContext) {
+    getReadSecurityState(readContext, requestContext);
+}
+function getReadSecurityState(readContext, requestContext) {
+    const root = getReadContextScope(readContext).root;
+    const authorityToken = requestAuthorityToken(requestContext);
+    const existing = readSecurityStates.get(root);
+    if (existing) {
+        if (existing.authorityToken !== authorityToken) {
+            throw ERR_VALIDATION({
+                message: 'ReadContext cannot be reused across request authorities',
+            });
         }
+        return existing;
+    }
+    const state = {
+        authorityToken,
+        domains: new WeakMap(),
+    };
+    readSecurityStates.set(root, state);
+    return state;
+}
+function getBeforeReadCacheEntry(readContext, requestContext, securityDomain, definition) {
+    const state = getReadSecurityState(readContext, requestContext);
+    let domain = state.domains.get(securityDomain);
+    if (!domain) {
+        domain = { definitions: new WeakMap() };
+        state.domains.set(securityDomain, domain);
     }
-    let combined;
-    if (predicates.length === 0) {
-        combined = null;
+    let definitionState = domain.definitions.get(definition);
+    if (!definitionState) {
+        definitionState = { modes: new Map() };
+        domain.definitions.set(definition, definitionState);
     }
-    else if (predicates.length === 1) {
-        combined = predicates[0];
+    const mode = requestContext.readMode ?? 'any';
+    let entry = definitionState.modes.get(mode);
+    if (!entry) {
+        entry = {};
+        definitionState.modes.set(mode, entry);
     }
-    else {
-        combined = { $and: predicates };
+    return entry;
+}
+/**
+ * `requestId` stays in the token deliberately. A `ReadContext` is a
+ * per-logical-request object, and predicates cached on it may embed
+ * request-time state (embargo cutoffs, preview windows), so reusing one
+ * across requests must fail loudly even for the same actor. The flip side
+ * is a contract on host adapters: a `RequestContext` factory must return
+ * the same instance for every call within one logical request (see
+ * `oncePerRequest` in `@byline/host-tanstack-start`) — a factory that
+ * mints a fresh `requestId` per call makes any two reads sharing a
+ * `ReadContext` throw the cross-authority error above.
+ */
+function requestAuthorityToken(requestContext) {
+    const actor = requestContext.actor;
+    if (actor == null) {
+        return JSON.stringify([requestContext.requestId, requestContext.locale ?? null, 'anonymous']);
     }
-    readContext.beforeReadCache.set(collectionPath, combined);
-    return combined;
+    const realm = 'isSuperAdmin' in actor ? 'admin' : 'user';
+    const isSuperAdmin = 'isSuperAdmin' in actor ? actor.isSuperAdmin : false;
+    return JSON.stringify([
+        requestContext.requestId,
+        requestContext.locale ?? null,
+        realm,
+        actor.id,
+        isSuperAdmin,
+        Array.from(actor.abilities).sort(),
+    ]);
 }
 /** Normalise a `beforeRead` slot (single function or array) into a flat array. */
 function normalizeBeforeReadHook(slot) {