canopycms 0.0.67 → 0.0.68-int.101

package/dist/content-listing.d.ts

@@ -3,7 +3,7 @@
  */
 import type { ContentFormat, FlatSchemaItem, EntrySchema } from './config/index.js';
 import type { LogicalPath, PhysicalPath, Slug, ContentId } from './paths/types.js';
-import { ContentStore, type ReferenceResolveCache } from './content-store.js';
+import { ContentStore, type ReferenceResolveCache, type ReferenceTargetAccess } from './content-store.js';
 /** An entry listing item with raw filesystem data; no API-specific fields like canEdit. */
 export interface CollectionListItem {
     logicalPath: LogicalPath;
@@ -105,9 +105,9 @@ export interface ListEntriesOptions<T = Record<string, unknown>> {
      * not per referencing entry, since a single {@link ReferenceResolveCache} spans the whole
      * call. Nothing is constructed and nothing is scanned when this is off.
      *
-     * **Path ACLs are not applied to the resolved targets**, matching `read()` exactly: a
-     * reference can resolve to an entry the user could not `read()` directly. The entries being
-     * LISTED are still ACL-filtered, and a filtered-out entry is never resolved at all.
+     * **Targets get the same path-ACL rule as `read()`**: a target the user may not read
+     * resolves to a `RestrictedReference` (title, URL, `unavailable: true`), never its data. A
+     * filtered-out entry is never resolved at all.
      */
     resolveReferences?: boolean;
 }
@@ -123,8 +123,8 @@ export interface ListEntriesOptions<T = Record<string, unknown>> {
  * unfiltered exactly as build-time callers want.
  */
 export interface ContentVisibilityOptions {
-    /** Return false to drop an entry. Receives the entry's branch-root-relative physical path. */
-    shouldInclude?: (physicalPath: PhysicalPath) => boolean;
+    /** Return false to drop an entry. Receives the entry's logical path (see `entryLogicalPath`). */
+    shouldInclude?: (logicalPath: LogicalPath) => boolean;
 }
 /** A collection node from the flattened schema. */
 export type CollectionSchemaItem = Extract<FlatSchemaItem, {
@@ -145,10 +145,13 @@ export type CollectionSchemaItem = Extract<FlatSchemaItem, {
  * whole batch. content-index-registry.ts holds stores through `WeakRef` + a
  * `FinalizationRegistry`, so these short-lived instances stay collectable.
  */
-export declare const createReferenceResolver: (branchRoot: string, flatSchema: FlatSchemaItem[], contentRootName: string) => {
+export declare const createReferenceResolver: (branchRoot: string, flatSchema: FlatSchemaItem[], contentRootName: string, visibility: ContentVisibilityOptions | undefined) => ListingReferenceResolver;
+/** What a listing call resolves references through; see {@link createReferenceResolver}. */
+export interface ListingReferenceResolver {
     store: ContentStore;
     cache: ReferenceResolveCache;
-};
+    access: ReferenceTargetAccess | undefined;
+}
 /**
  * Resolve `reference` fields in a collection's listed entries, in place of their raw data.
  *
@@ -157,10 +160,7 @@ export declare const createReferenceResolver: (branchRoot: string, flatSchema: F
  * what says which fields are references at all; an entry whose type has no resolvable schema
  * is returned untouched rather than guessed at.
  */
-export declare const resolveCollectionItemReferences: (items: CollectionListItem[], collection: CollectionSchemaItem, resolver: {
-    store: ContentStore;
-    cache: ReferenceResolveCache;
-}) => Promise<CollectionListItem[]>;
+export declare const resolveCollectionItemReferences: (items: CollectionListItem[], collection: CollectionSchemaItem, resolver: ListingReferenceResolver) => Promise<CollectionListItem[]>;
 /**
  * List all content entries as a flat array: walks the schema to discover collections, reads
  * entries from each, and returns a flat list suitable for generateStaticParams, search

package/dist/content-listing.js

@@ -9,7 +9,7 @@ import { findBodyFieldName } from './utils/body-field.js';
 import { computeEntryUrl } from './utils/entry-url.js';
 import { asRecord, getFormatExtension } from './utils/format.js';
 import { resolveCollectionPath } from './content-id-index.js';
-import { validateAndNormalizePath } from './paths/index.js';
+import { entryLogicalPath, validateAndNormalizePath } from './paths/index.js';
 import { isNotFoundError, getErrorMessage } from './utils/error.js';
 import { createDebugLogger } from './utils/debug.js';
 import { ContentStore, ContentStoreError, createReferenceResolveCache, } from './content-store.js';
@@ -81,9 +81,13 @@ import { parseTypedFilename } from './utils/typed-filename.js';
  * whole batch. content-index-registry.ts holds stores through `WeakRef` + a
  * `FinalizationRegistry`, so these short-lived instances stay collectable.
  */
-export const createReferenceResolver = (branchRoot, flatSchema, contentRootName) => ({
+export const createReferenceResolver = (branchRoot, flatSchema, contentRootName, visibility) => ({
     store: new ContentStore(branchRoot, flatSchema, { contentRootName }),
     cache: createReferenceResolveCache(),
+    // The predicate that hides an entry from the listing is the one that restricts it as a
+    // reference target, so a target is never shown in a sibling's data that its own listing
+    // row would have hidden.
+    access: visibility?.shouldInclude,
 });
 /**
  * Resolve `reference` fields in a collection's listed entries, in place of their raw data.
@@ -99,7 +103,7 @@ export const resolveCollectionItemReferences = async (items, collection, resolve
         return item;
     return {
         ...item,
-        data: await resolver.store.resolveReferences(item.data, fields, resolver.cache),
+        data: await resolver.store.resolveReferences(item.data, fields, resolver.cache, resolver.access),
     };
 }));
 /**
@@ -135,11 +139,11 @@ export async function listEntries(branchRoot, flatSchema, contentRootName, optio
     // One store + cache for the whole call, or nothing at all when the caller did not opt in.
     // See the `resolveReferences` option for the cost this buys back.
     const resolver = options?.resolveReferences
-        ? createReferenceResolver(branchRoot, flatSchema, contentRootName)
+        ? createReferenceResolver(branchRoot, flatSchema, contentRootName, visibility)
         : null;
     const collectionResults = await Promise.all(collections.map(async (collection) => {
         const entries = await listCollectionEntries(branchRoot, collection, (file) => skippedFiles.push(file));
-        const visible = shouldInclude ? entries.filter((e) => shouldInclude(e.physicalPath)) : entries;
+        const visible = shouldInclude ? entries.filter((e) => shouldInclude(e.logicalPath)) : entries;
         // Resolve AFTER the visibility filter (a denied entry is never resolved, so its
         // references cost nothing and leak nothing) and BEFORE the mapping below, so
         // `extract` and `filter` both see resolved data — which is the entire point.
@@ -330,7 +334,7 @@ export const listCollectionEntries = async (root, collection, onSkip) => {
             readEntryData(absolutePath, format, bodyField),
         ]);
         const item = {
-            logicalPath: `${collection.logicalPath}/${slug}`,
+            logicalPath: entryLogicalPath(collection.logicalPath, slug),
             contentId,
             slug,
             collectionPath: collection.logicalPath,

package/dist/content-reader.d.ts

@@ -7,7 +7,16 @@ export interface ContentReaderOptions {
     basePathOverride?: string;
     defaultBranch?: string;
     createdBy?: string;
+    /**
+     * Provision a workspace for a branch that has none. Off by default: a `branch` handed in from a
+     * request (`?branch=`) would otherwise let any visitor create a workspace per distinct name, so
+     * turn it on only when every branch name the reader sees is trusted.
+     */
     allowCreateBranch?: boolean;
+    /**
+     * The sole branch resolver when given, replacing `allowCreateBranch`: null reads as NOT_FOUND.
+     * Reads from the checkout (static deployments, builds) never call it.
+     */
     getBranchContext?: (branch: string) => Promise<BranchContext | null>;
 }
 export interface ReadContentInput {
@@ -84,7 +93,7 @@ export interface ContentReader {
     }>;
 }
 /**
- * Server-side helper to read content directly from a branch workspace.
- * Falls back to creating the branch workspace (metadata + checkout) if missing.
+ * Server-side helper to read content directly from a branch workspace. A branch with no workspace
+ * reads as NOT_FOUND unless `allowCreateBranch` or a `getBranchContext` resolver says otherwise.
  */
 export declare const createContentReader: (options: ContentReaderOptions) => ContentReader;

package/dist/content-reader.js

@@ -1,14 +1,14 @@
 import { loadBranchContext, loadOrCreateBranchContext } from './branch-workspace.js';
 import { ContentStore, ContentStoreError } from './content-store.js';
-import { resolveBranchPaths, } from './paths/index.js';
+import { namesNoWorkspace, resolveBranchPaths, } from './paths/index.js';
 import { trimSlashes } from './paths/normalize.js';
 import { isIndexSlug } from './utils/entry-url.js';
 import { isDeployedStatic, isBuildMode, readsFromCheckout } from './build-mode.js';
 import { isNotFoundError } from './utils/error.js';
 import { resolveEntryLinksInData } from './entry-link-resolver.js';
 /**
- * Server-side helper to read content directly from a branch workspace.
- * Falls back to creating the branch workspace (metadata + checkout) if missing.
+ * Server-side helper to read content directly from a branch workspace. A branch with no workspace
+ * reads as NOT_FOUND unless `allowCreateBranch` or a `getBranchContext` resolver says otherwise.
  */
 export const createContentReader = (options) => {
     const services = options.services;
@@ -18,7 +18,7 @@ export const createContentReader = (options) => {
         services.config.defaultActiveBranch ??
         services.config.defaultBaseBranch ??
         'main';
-    const allowCreateBranch = options.allowCreateBranch ?? true;
+    const allowCreateBranch = options.allowCreateBranch ?? false;
     const createdBy = options.createdBy ?? 'canopycms-content-reader';
     const resolveBranchContext = async (branchName) => {
         // Static deployments and builds read from the checkout: loadOrCreateBranchContext
@@ -34,11 +34,11 @@ export const createContentReader = (options) => {
                 remoteUrl: services.config.defaultRemoteUrl,
             });
         }
-        // Check custom resolver first (e.g., from HTTP handler)
         if (options.getBranchContext) {
-            const existing = await options.getBranchContext(branchName);
-            if (existing)
-                return existing;
+            const resolved = await options.getBranchContext(branchName);
+            if (!resolved)
+                throw new ContentStoreError(`Branch not found: ${branchName}`, 'NOT_FOUND');
+            return resolved;
         }
         if (allowCreateBranch) {
             return loadOrCreateBranchContext({
@@ -50,11 +50,14 @@ export const createContentReader = (options) => {
                 remoteUrl: services.config.defaultRemoteUrl,
             });
         }
-        // Not allowed to create — must exist
         const existing = await loadBranchContext({
             branchName,
             mode: operatingMode,
             basePathOverride,
+        }).catch((err) => {
+            if (namesNoWorkspace(err))
+                return null;
+            throw err;
         });
         if (!existing)
             throw new ContentStoreError(`Branch not found: ${branchName}`, 'NOT_FOUND');
@@ -128,10 +131,10 @@ export const createContentReader = (options) => {
             throw new ContentStoreError(`Path is not a collection: ${entryPath}`, 'NO_SCHEMA_ITEM');
         }
         // Get the path WITHOUT reading the file
-        let relativePath;
+        let logicalPath;
         // Absolute filesystem path to the entry file. Surfaced on read() / readByUrlPath()
         // for server-side colocated-artifact reads (e.g. a sibling profile.json). Already
-        // computed here for permission checks; just carried through.
+        // computed here by path resolution; just carried through.
         let physicalPath;
         // Entry type + content ID come out of path resolution (buildPaths() derives both from the
         // schema item / filename), surfaced on read() / readByUrlPath() so callers can route or
@@ -140,7 +143,7 @@ export const createContentReader = (options) => {
         let entryId;
         try {
             const resolved = await store.resolveDocumentPath(entryPath, slug ?? '');
-            relativePath = resolved.relativePath;
+            logicalPath = resolved.logicalPath;
             physicalPath = resolved.absolutePath;
             // resolveDocumentPath() always sets entryTypeName for a valid schema item, so no
             // further fallback is needed here; `id` is the one field that can be legitimately
@@ -161,10 +164,14 @@ export const createContentReader = (options) => {
         if (input.urlAddressableOnly && !store.declaresEntryType(entryPath, entryType)) {
             throw new ContentStoreError(`Entry type '${entryType}' is not declared by ${entryPath}`, 'NO_SCHEMA_ITEM');
         }
-        // Check permissions BEFORE reading the file (security)
+        // Check permissions BEFORE reading the file (security). The same checker then judges every
+        // reference target, so a reference cannot carry a target's data past these rules.
         const shouldCheckPermissions = !(isDeployedStatic(services.config) || isBuildMode());
+        let referenceAccess;
         if (shouldCheckPermissions) {
-            const access = await services.checkContentAccess(context, branchRoot, relativePath, user, 'read');
+            const checkAccess = await services.createContentAccessChecker(context, branchRoot, user);
+            referenceAccess = (targetPath) => checkAccess(targetPath, 'read').allowed;
+            const access = checkAccess(logicalPath, 'read');
             if (!access.allowed) {
                 if (services.config.mode !== 'prod') {
                     const reasons = [];
@@ -187,6 +194,7 @@ export const createContentReader = (options) => {
         try {
             const doc = await store.read(entryPath, slug ?? '', {
                 resolveReferences: input.resolveReferences ?? true,
+                referenceAccess,
             });
             return { doc, store, physicalPath, entryType, entryId };
         }

package/dist/content-store.d.ts

@@ -148,7 +148,8 @@ export interface ContentStoreOptions {
  * shorter than the `ContentStore` whose memoized `idIndex()` it sits on, so it adds no
  * staleness window and is out of scope for the generation-marker protocol in
  * `docs/concurrency.md`. Never make one module-global, persist one, or reuse one across
- * requests.
+ * requests. A cached value has the batch's {@link ReferenceTargetAccess} already applied, so a
+ * cache must never be shared by two readers.
  *
  * Misses are memoized alongside hits so one batch stays internally coherent: a shared block
  * resolving to data on page 1 and `null` on page 40 of one sitemap is worse than either
@@ -157,6 +158,21 @@ export interface ContentStoreOptions {
 export type ReferenceResolveCache = Map<string, Promise<Record<string, unknown> | null>>;
 /** Create a cache for one batch of reference resolution. See {@link ReferenceResolveCache}. */
 export declare const createReferenceResolveCache: () => ReferenceResolveCache;
+/**
+ * Whether the reader may see a reference's target in full, given the target's logical path
+ * (`entryLogicalPath`). A denied target resolves to a `RestrictedReference` (entry-schema.ts).
+ *
+ * Built from `services.createContentAccessChecker` for the request's user, so reference
+ * targets are judged by the same rules as the entry being read. Omitted, every target resolves
+ * in full, which is what a build and a static deployment want (merged content is public there).
+ * Every request-time surface that returns resolved data to a user passes one.
+ */
+export type ReferenceTargetAccess = (logicalPath: LogicalPath) => boolean;
+export interface ReadOptions {
+    resolveReferences?: boolean;
+    /** See {@link ReferenceTargetAccess}. */
+    referenceAccess?: ReferenceTargetAccess;
+}
 export declare class ContentStore {
     private readonly root;
     /** See ContentStoreOptions.contentRootName — the ID index scan root. */
@@ -347,6 +363,8 @@ export declare class ContentStore {
     resolveDocumentPath(schemaPath: LogicalPath, slug?: string): Promise<{
         absolutePath: string;
         relativePath: PhysicalPath;
+        /** The entry's logical path, the form path-permission rules match (`entryLogicalPath`). */
+        logicalPath: LogicalPath;
         id?: string;
         /**
          * Always populated for a valid schema item: the collection branch below resolves a name
@@ -363,9 +381,11 @@ export declare class ContentStore {
          */
         existed: boolean;
     }>;
-    read(collectionPath: LogicalPath, slug?: Slug | '', options?: {
-        resolveReferences?: boolean;
-    }): Promise<ContentDocument>;
+    /**
+     * Read one entry. References resolve unless `resolveReferences: false`; a target that
+     * `referenceAccess` denies resolves to a `RestrictedReference` rather than its data.
+     */
+    read(collectionPath: LogicalPath, slug?: Slug | '', options?: ReadOptions): Promise<ContentDocument>;
     write(collectionPath: LogicalPath, slug: (Slug | "") | undefined, input: WriteInput, entryTypeName?: string, existingId?: ContentId): Promise<ContentDocument>;
     /**
      * Read an entry by its ID (UUID).
@@ -457,12 +477,15 @@ export declare class ContentStore {
      * a target referenced by many entries is read once; omit `cache` for exactly `read()`'s
      * unmemoized behavior.
      *
-     * **Path ACLs are not consulted for the targets.** Resolution goes through this store's own
-     * `read()`, below the per-entry permission check in content-reader.ts, so a resolved target
-     * may be an entry the caller could not `read()` directly -- pre-existing `read()` behavior,
-     * matched here on purpose so one rule covers both.
+     * `access` applies to every target exactly as in `read()`; see {@link ReferenceTargetAccess}.
+     */
+    resolveReferences(data: Record<string, unknown>, fields: EntrySchema, cache?: ReferenceResolveCache, access?: ReferenceTargetAccess): Promise<Record<string, unknown>>;
+    /**
+     * Resolve one reference id the way a reference field resolves it, for the editor's
+     * live-preview endpoint (api/resolve-references.ts), which has ids but no field to walk. Null
+     * when the id names no entry. No body is embedded, since there is no field to ask for one.
      */
-    resolveReferences(data: Record<string, unknown>, fields: EntrySchema, cache?: ReferenceResolveCache): Promise<Record<string, unknown>>;
+    resolveReferenceTarget(id: string, access?: ReferenceTargetAccess): Promise<Record<string, unknown> | null>;
     private resolveReferencesInData;
     /**
      * Resolve a single reference ID to full entry data, memoized when a batch cache is supplied.
@@ -503,5 +526,10 @@ export declare class ContentStore {
      * still runs the full refresh-and-retry; a cache only makes repeats of the SAME id share it.
      */
     private resolveSingleReferenceUncached;
+    /**
+     * The entry type an entry file was written as, by its filename's type token, falling back to
+     * the collection's default the way `read()` does for a legacy untyped file.
+     */
+    private entryTypeOf;
     private resolveSingleReferenceOnce;
 }

package/dist/content-store.js

@@ -20,7 +20,8 @@ import { serializeFrontmatter, serializeYaml } from './utils/content-serialize.j
 import { withLock } from './utils/async-mutex.js';
 import { ContentWriteLockBusyError, DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS, withContentWriteLock, } from './utils/content-write-lock.js';
 import { findBodyFieldName } from './utils/body-field.js';
-import { buildResolvedReference } from './entry-schema.js';
+import { buildResolvedReference, buildRestrictedReference } from './entry-schema.js';
+import { resolveEntryTitle } from './utils/title-field.js';
 import { computeEntryUrl } from './utils/entry-url.js';
 import { findUrlPathClaimant } from './url-collision.js';
 import { ContentIdIndex, extractIdFromFilename, extractSlugFromFilename, extractEntryTypeFromFilename, resolveCollectionPath, } from './content-id-index.js';
@@ -30,7 +31,7 @@ import { generateId } from './id.js';
 import { isNodeError } from './utils/error.js';
 import { filePathExists, readFileIfExists } from './utils/fs.js';
 import { asRecord, getFormatExtension } from './utils/format.js';
-import { normalizeFilesystemPath, parseSlug, } from './paths/index.js';
+import { entryLogicalPath, normalizeFilesystemPath, parseSlug, } from './paths/index.js';
 /**
  * Acquire `keys` in canonical (sorted) order before running `fn`, ruling out AB-BA
  * deadlocks between callers with overlapping key sets. Only renameEntry() needs two
@@ -602,6 +603,7 @@ export class ContentStore {
             return {
                 absolutePath: resolved,
                 relativePath: path.relative(this.root, resolved),
+                logicalPath: entryLogicalPath(schemaItem.logicalPath, safeSlug),
                 id,
                 entryTypeName: finalEntryTypeName,
                 existed,
@@ -632,6 +634,10 @@ export class ContentStore {
         const schemaItem = this.assertSchemaItem(schemaPath);
         return await this.buildPaths(schemaItem, slug);
     }
+    /**
+     * Read one entry. References resolve unless `resolveReferences: false`; a target that
+     * `referenceAccess` denies resolves to a `RestrictedReference` rather than its data.
+     */
     async read(collectionPath, slug = '', options = {}) {
         const schemaItem = this.assertSchemaItem(collectionPath);
         const { absolutePath, relativePath, entryTypeName: resolvedEntryTypeName, } = await this.buildPaths(schemaItem, slug);
@@ -702,7 +708,7 @@ export class ContentStore {
             };
         }
         if (options.resolveReferences !== false) {
-            doc.data = await this.resolveReferencesInData(doc.data, fields);
+            doc.data = await this.resolveReferencesInData(doc.data, fields, undefined, options.referenceAccess);
         }
         doc.version = stat.mtimeMs;
         return doc;
@@ -1382,21 +1388,26 @@ export class ContentStore {
      * a target referenced by many entries is read once; omit `cache` for exactly `read()`'s
      * unmemoized behavior.
      *
-     * **Path ACLs are not consulted for the targets.** Resolution goes through this store's own
-     * `read()`, below the per-entry permission check in content-reader.ts, so a resolved target
-     * may be an entry the caller could not `read()` directly -- pre-existing `read()` behavior,
-     * matched here on purpose so one rule covers both.
+     * `access` applies to every target exactly as in `read()`; see {@link ReferenceTargetAccess}.
+     */
+    async resolveReferences(data, fields, cache, access) {
+        return this.resolveReferencesInData(data, fields, cache, access);
+    }
+    /**
+     * Resolve one reference id the way a reference field resolves it, for the editor's
+     * live-preview endpoint (api/resolve-references.ts), which has ids but no field to walk. Null
+     * when the id names no entry. No body is embedded, since there is no field to ask for one.
      */
-    async resolveReferences(data, fields, cache) {
-        return this.resolveReferencesInData(data, fields, cache);
+    async resolveReferenceTarget(id, access) {
+        return this.resolveSingleReference(id, await this.idIndex(), false, undefined, access);
     }
-    async resolveReferencesInData(data, fields, cache) {
+    async resolveReferencesInData(data, fields, cache, access) {
         const resolved = { ...data };
         const idIndex = await this.idIndex();
         for (const field of fields) {
             // Inline groups are transparent — recurse into their children at the same data level
             if (field.type === 'group') {
-                const groupResolved = await this.resolveReferencesInData(resolved, field.fields, cache);
+                const groupResolved = await this.resolveReferencesInData(resolved, field.fields, cache, access);
                 Object.assign(resolved, groupResolved);
                 continue;
             }
@@ -1407,11 +1418,11 @@ export class ContentStore {
                 // which routinely contains both kinds at once. See ReferenceFieldConfig.includeBody.
                 const includeBody = field.includeBody === true;
                 if (typeof value === 'string' && value) {
-                    resolved[field.name] = await this.resolveSingleReference(value, idIndex, includeBody, cache);
+                    resolved[field.name] = await this.resolveSingleReference(value, idIndex, includeBody, cache, access);
                 }
                 else if (field.list && Array.isArray(value)) {
                     resolved[field.name] = await Promise.all(value.map((id) => typeof id === 'string'
-                        ? this.resolveSingleReference(id, idIndex, includeBody, cache)
+                        ? this.resolveSingleReference(id, idIndex, includeBody, cache, access)
                         : null));
                 }
             }
@@ -1421,11 +1432,11 @@ export class ContentStore {
                     continue;
                 if (objectField.list && Array.isArray(value)) {
                     resolved[field.name] = await Promise.all(value.map((item) => typeof item === 'object' && item !== null
-                        ? this.resolveReferencesInData(item, objectField.fields, cache)
+                        ? this.resolveReferencesInData(item, objectField.fields, cache, access)
                         : item));
                 }
                 else if (typeof value === 'object') {
-                    resolved[field.name] = await this.resolveReferencesInData(value, objectField.fields, cache);
+                    resolved[field.name] = await this.resolveReferencesInData(value, objectField.fields, cache, access);
                 }
             }
             else if (field.type === 'block' && Array.isArray(value)) {
@@ -1439,7 +1450,7 @@ export class ContentStore {
                         return block;
                     return {
                         ...b,
-                        value: await this.resolveReferencesInData(b.value, template.fields, cache),
+                        value: await this.resolveReferencesInData(b.value, template.fields, cache, access),
                     };
                 }));
             }
@@ -1470,9 +1481,9 @@ export class ContentStore {
      * `includeBody` is opt-in per field: an embedded body sits inside the memoized object and is
      * cloned once per referencing entry.
      */
-    resolveSingleReference(id, idIndex, includeBody, cache) {
+    resolveSingleReference(id, idIndex, includeBody, cache, access) {
         if (!cache)
-            return this.resolveSingleReferenceUncached(id, idIndex, includeBody);
+            return this.resolveSingleReferenceUncached(id, idIndex, includeBody, access);
         // The key carries `includeBody`, not just the id: two fields can reference the SAME target
         // with different settings, and sharing one entry between them would make the shape depend
         // on which field the walk reached first.
@@ -1482,7 +1493,7 @@ export class ContentStore {
             // Store the in-flight promise with no `await` in between, so concurrent lookups from
             // one Promise.all batch find it and collapse onto a single read. Memoizing the promise
             // also shares the self-healing retry below rather than repeating it.
-            pending = this.resolveSingleReferenceUncached(id, idIndex, includeBody);
+            pending = this.resolveSingleReferenceUncached(id, idIndex, includeBody, access);
             cache.set(key, pending);
         }
         // The cached promise always has this handler attached, so it is never an unhandled
@@ -1503,18 +1514,30 @@ export class ContentStore {
      * A {@link ReferenceResolveCache} sits ABOVE this, never inside it, so every distinct id
      * still runs the full refresh-and-retry; a cache only makes repeats of the SAME id share it.
      */
-    async resolveSingleReferenceUncached(id, idIndex, includeBody) {
-        const first = await this.resolveSingleReferenceOnce(id, idIndex, includeBody);
+    async resolveSingleReferenceUncached(id, idIndex, includeBody, access) {
+        const first = await this.resolveSingleReferenceOnce(id, idIndex, includeBody, access);
         if (first !== STALE_LOOKUP)
             return first;
         // Force a rebuild (throttled). Even when this caller loses the throttle, retry against the
         // live index: a sibling lookup in the same batch may have won it and rebuilt (idIndex()
         // dedupes in-flight builds), so every miss in a Promise.all batch heals.
         await this.refreshIndexForSuspiciousLookup();
-        const second = await this.resolveSingleReferenceOnce(id, await this.idIndex(), includeBody);
+        const second = await this.resolveSingleReferenceOnce(id, await this.idIndex(), includeBody, access);
         return second === STALE_LOOKUP ? null : second;
     }
-    async resolveSingleReferenceOnce(id, idIndex, includeBody) {
+    /**
+     * The entry type an entry file was written as, by its filename's type token, falling back to
+     * the collection's default the way `read()` does for a legacy untyped file.
+     */
+    entryTypeOf(collectionPath, relativePath) {
+        const schemaItem = this.assertSchemaItem(collectionPath);
+        if (schemaItem.type === 'entry-type')
+            return schemaItem;
+        const entries = schemaItem.entries;
+        const typeName = extractEntryTypeFromFilename(path.basename(relativePath));
+        return entries?.find((e) => e.name === typeName) ?? getDefaultEntryType(schemaItem.entries);
+    }
+    async resolveSingleReferenceOnce(id, idIndex, includeBody, access) {
         try {
             const location = idIndex.findById(id);
             if (!location)
@@ -1526,32 +1549,36 @@ export class ContentStore {
             const doc = await this.read(location.collection, location.slug, {
                 resolveReferences: false,
             });
-            // `urlPath` is what makes a resolved reference linkable: without it a page rendering
-            // "see also: <Target>" as a real anchor has no href from the resolution it already paid
-            // for, and had to run a SECOND full listing over the tree to build a contentId -> url
-            // table.
-            //
-            // Deliberately `computeEntryUrl` (utils/entry-url.ts), the same forward
-            // collection+slug -> url rule `listEntries` publishes as `item.urlPath` and
+            // `urlPath` is what makes a resolved reference linkable without a second listing pass to
+            // build a contentId -> url table. Deliberately `computeEntryUrl` (utils/entry-url.ts), the
+            // forward collection+slug -> url rule `listEntries` publishes as `item.urlPath` and
             // `entry-link-resolver.ts` uses for `entry:ID` links -- NOT the reverse url -> entry
-            // resolver in url-path-resolver.ts. They agree today, but direction matters: this is the
-            // surface that DEFINES an entry's URL, so sourcing it from the resolver that consumes
-            // that definition would invert the dependency.
-            //
-            // The assembly -- data, then the embedded body, then the reserved metadata -- is
-            // `buildResolvedReference`'s job, because api/resolve-references.ts builds the same
-            // object for live preview and the two had drifted; its doc comment carries the ordering.
+            // resolver in url-path-resolver.ts: this is the surface that DEFINES an entry's URL, so
+            // sourcing it from the resolver that consumes that definition would invert the dependency.
+            const meta = {
+                id,
+                slug: location.slug,
+                collection: location.collection,
+                urlPath: computeEntryUrl(location.collection, location.slug, this.contentRootName),
+            };
+            // Checked on the target's logical path, the space path rules are written in. The title is
+            // the same `resolveEntryTitle` chain the entries API labels a listed entry with.
+            if (access && !access(entryLogicalPath(location.collection, location.slug))) {
+                const entryType = this.entryTypeOf(location.collection, location.relativePath);
+                return buildRestrictedReference(meta, resolveEntryTitle(doc.data, {
+                    schema: entryType?.schema,
+                    entryTypeLabel: entryType?.label,
+                    slug: location.slug,
+                }));
+            }
+            // `buildResolvedReference` owns the assembly order (data, embedded body, reserved
+            // metadata); its doc comment says why the order is the contract.
             //
             // `'body' in doc` narrows the ContentDocument union to its markdown variant, so
             // `doc.body`/`doc.bodyFieldName` are reachable at all -- a type guard, not a redundant
             // runtime check. Only a field that asked to EMBED its target passes a body at all.
             const bodyForEmbed = includeBody && 'body' in doc ? { fieldName: doc.bodyFieldName, value: doc.body } : undefined;
-            return buildResolvedReference(doc.data, {
-                id,
-                slug: location.slug,
-                collection: location.collection,
-                urlPath: computeEntryUrl(location.collection, location.slug, this.contentRootName),
-            }, bodyForEmbed);
+            return buildResolvedReference(doc.data, meta, bodyForEmbed);
         }
         catch (error) {
             // Index hit but the file is gone — the typical symptom of an external

package/dist/content-tree.d.ts

@@ -136,7 +136,7 @@ export interface BuildContentTreeOptions<T = unknown, TEntryTypes = DefaultEntry
      *
      * Same flag, same default (`false`) and same reasoning as
      * `ListEntriesOptions.resolveReferences` in content-listing.ts — see it for why the default
-     * is opt-in, what it costs, and why path ACLs are not applied to the resolved targets.
+     * is opt-in, what it costs, and how path ACLs apply to the resolved targets.
      */
     resolveReferences?: boolean;
 }

package/dist/content-tree.js

@@ -70,11 +70,11 @@ export async function buildContentTree(branchRoot, flatSchema, contentRootName,
     // read once for the entire tree rather than once per collection. Null unless opted in —
     // see the `resolveReferences` option above.
     const resolver = options?.resolveReferences
-        ? createReferenceResolver(branchRoot, flatSchema, contentRootName)
+        ? createReferenceResolver(branchRoot, flatSchema, contentRootName, visibility)
         : null;
     const listVisibleEntries = async (collection) => {
         const entries = await listCollectionEntries(branchRoot, collection);
-        const visible = shouldInclude ? entries.filter((e) => shouldInclude(e.physicalPath)) : entries;
+        const visible = shouldInclude ? entries.filter((e) => shouldInclude(e.logicalPath)) : entries;
         // Resolved here rather than at the two node-building sites so BOTH inherit it — the same
         // reason the ACL filter lives here. A denied entry is filtered above and never resolved.
         return resolver ? resolveCollectionItemReferences(visible, collection, resolver) : visible;