canopycms 0.0.67 → 0.0.68-int.100

package/dist/assets/transform-directives.js

@@ -4,17 +4,16 @@
  * NO imports (not even other files in this directory) so it can be imported
  * from client bundles (via `assetUrl`/`assetSrcSet` in asset-url.ts, exported
  * off the package's main entry) as well as from the server-only transform
- * engine (transform.ts) and the prod transform Lambda, without
+ * engine (transform.ts) and the lazy transform Lambda, without
  * ever pulling in node:crypto, sharp, or any other server-only dependency.
  *
  * `{directives}` is either the literal identity token (`orig`) or a
  * comma-separated list of `key=value` pairs drawn from:
- *   w={int}   output width - allowlisted to multiples of 160 in [160, 4096]
- *             (bounds cache-stuffing; upscaling is rejected at transform
- *             time via `withoutEnlargement`, not here)
+ *   w={int}   output width, accepted per `TransformWidthPolicy` (upscaling
+ *             is rejected at transform time via `withoutEnlargement`, not here)
  *   f={fmt}   output format: webp | jpeg | png - when present, the URL's
  *             `{ext}` must equal it exactly
- *   q={int}   quality 1..100 (encoder-dependent)
+ *   q={int}   quality, a multiple of 5 in [30, 95] under either policy
  *   c={rect}  normalized crop rect `x:y:w:h`, four floats in [0,1] with
  *             x+w<=1 and y+h<=1, w>0 and h>0 (colon-separated - commas are
  *             the directive separator)
@@ -24,9 +23,11 @@
  */
 /** The identity transform directive name - EXIF-strip only, no other change. */
 export const IDENTITY_TRANSFORM_DIRECTIVE = 'orig';
-const MIN_WIDTH = 160;
-const MAX_WIDTH = 4096;
-const WIDTH_STEP = 160;
+const MIN_ALLOWLIST_WIDTH = 160;
+const MAX_ALLOWLIST_WIDTH = 4096;
+const ALLOWLIST_WIDTH_STEP = 160;
+const SMALL_ALLOWLIST_WIDTHS = new Set([32, 48, 64, 96, 128]);
+const MAX_ANY_WIDTH = 8192;
 /**
  * Decompression-bomb cap: the max `width * height` (post-decode pixel count)
  * any raster the pipeline handles may have - checked both at upload finalize
@@ -34,12 +35,14 @@ const WIDTH_STEP = 160;
  * time (transform.ts, via sharp's `limitInputPixels`). Shared here (rather
  * than duplicated in each server-only module) so it stays a single number,
  * and because this file is dependency-free/isomorphic it can be imported by
- * both without pulling sharp or file-type into anything. 4096x4096 (16.7 MP)
- * comfortably covers the largest output this system ever serves (MAX_WIDTH)
- * while still bounding decode-time memory for a small/compressible-but-huge
- * source (e.g. a 30000x30000 solid-color PNG).
+ * both without pulling sharp or file-type into anything. 24 MP (a 6000x4000
+ * camera frame) is sized by measured peak memory: the worst case, a full-size
+ * WebP encode of an RGBA WebP source, peaks at 1246 MiB here and grows about
+ * 37 MiB per MP, so this is the largest cap that fits the 2048 MB CMS and
+ * transform Lambdas with allocator headroom. For an animation the cap bounds
+ * all decoded frames together.
  */
-export const MAX_INPUT_PIXELS = 4096 * 4096;
+export const MAX_INPUT_PIXELS = 6000 * 4000;
 /**
  * Cap on decoded animated frames (GIF/WebP) - without this, `{ animated: true }`
  * (sharp's `pages: -1`) decodes every frame of a maliciously-crafted
@@ -61,12 +64,17 @@ export const MAX_ANIMATED_FRAMES = 60;
 // Quality is allowlisted (multiples of 5 in [30, 95] - 14 values) for the
 // same cache-stuffing reason as width: every accepted directive combination
 // becomes a stored cache object in prod, so unbounded q would multiply the
-// per-asset variant space by 100. Crop remains the one effectively unbounded
-// dimension (editor rects need float precision) - prod mitigation (rate
-// limiting / signed crops) is tracked in the design record for the CDK PR.
+// per-asset variant space by 100. Crop stays effectively unbounded (editor
+// rects need float precision); the public path answers it by computing nothing
+// (ARCHITECTURE.md, "Why transform by URL directive and materialize at release?").
 const MIN_QUALITY = 30;
 const MAX_QUALITY = 95;
 const QUALITY_STEP = 5;
+/**
+ * Decimal places a crop value keeps in its canonical form. The editor rounds a
+ * new crop to this (editor/media/crop-math.ts), so a crop the editor stores is
+ * already canonical; a URL carrying more decimals canonicalizes to the rounded rect.
+ */
 const CROP_PRECISION = 4;
 const HASH32_RE = /^[a-f0-9]{32}$/;
 const SLUG_RE = /^[a-z0-9-]+$/;
@@ -85,15 +93,22 @@ const KNOWN_DIRECTIVE_KEYS = new Set(['w', 'f', 'q', 'c']);
 function isOutputFormat(value) {
     return value === 'webp' || value === 'jpeg' || value === 'png';
 }
-/** True if `width` is on the allowlist: a multiple of 160 in [160, 4096]. */
-export function isAllowedTransformWidth(width) {
-    return (Number.isInteger(width) && width >= MIN_WIDTH && width <= MAX_WIDTH && width % WIDTH_STEP === 0);
+/** True if `policy` accepts `width`; see `TransformWidthPolicy`. */
+export function isAllowedTransformWidth(width, policy) {
+    if (!Number.isInteger(width))
+        return false;
+    if (policy === 'any')
+        return width >= 1 && width <= MAX_ANY_WIDTH;
+    return (SMALL_ALLOWLIST_WIDTHS.has(width) ||
+        (width >= MIN_ALLOWLIST_WIDTH &&
+            width <= MAX_ALLOWLIST_WIDTH &&
+            width % ALLOWLIST_WIDTH_STEP === 0));
 }
-function parseWidth(value) {
+function parseWidth(value, policy) {
     if (!POSITIVE_INT_RE.test(value))
         return null;
     const n = Number(value);
-    return isAllowedTransformWidth(n) ? n : null;
+    return isAllowedTransformWidth(n, policy) ? n : null;
 }
 /** True if `quality` is on the allowlist: a multiple of 5 in [30, 95]. */
 function isAllowedTransformQuality(quality) {
@@ -145,6 +160,27 @@ function parseCrop(value) {
         return null;
     return { x, y, w, h };
 }
+function roundToCropPrecision(n) {
+    const factor = 10 ** CROP_PRECISION;
+    return Math.round(n * factor) / factor;
+}
+/**
+ * Round a crop rect to `CROP_PRECISION` decimals, shrinking `w`/`h` to the
+ * space left when rounding pushes `x+w` or `y+h` past 1 (0.66665 + 0.33335
+ * rounds to 0.6667 + 0.3334). The result can still be degenerate (a `w` or `h`
+ * that rounds to 0), which `isValidCropRect` rejects.
+ */
+export function roundCropRect(rect) {
+    const x = roundToCropPrecision(rect.x);
+    const y = roundToCropPrecision(rect.y);
+    let w = roundToCropPrecision(rect.w);
+    let h = roundToCropPrecision(rect.h);
+    if (x + w > 1)
+        w = roundToCropPrecision(1 - x);
+    if (y + h > 1)
+        h = roundToCropPrecision(1 - y);
+    return { x, y, w, h };
+}
 function formatUnitFloat(n) {
     return n.toFixed(CROP_PRECISION);
 }
@@ -156,7 +192,7 @@ function err(error) {
  * `assets/t/` and the hash32 segment) into a `TransformDirectives`, or
  * `orig` into the identity directive.
  */
-function parseDirectivesString(raw) {
+function parseDirectivesString(raw, policy) {
     if (raw === IDENTITY_TRANSFORM_DIRECTIVE) {
         return { ok: true, directives: { identity: true } };
     }
@@ -187,7 +223,7 @@ function parseDirectivesString(raw) {
         seen.add(key);
         switch (key) {
             case 'w': {
-                const w = parseWidth(value);
+                const w = parseWidth(value, policy);
                 if (w === null)
                     return err(`Invalid width: '${value}'`);
                 width = w;
@@ -222,7 +258,7 @@ function parseDirectivesString(raw) {
  * `[directivesRaw, hash32, "{slug}.{ext}"]`. The raw route strips the
  * `assets/t/` prefix and splits the remaining key by `/` before calling this.
  */
-export function parseTransformPath(segments) {
+export function parseTransformPath(segments, policy) {
     if (segments.length !== 3) {
         return err(`Expected 3 path segments (directives/hash32/slug.ext), got ${segments.length}`);
     }
@@ -242,7 +278,7 @@ export function parseTransformPath(segments) {
     if (!EXT_RE.test(ext)) {
         return err(`Invalid ext: '${ext}'`);
     }
-    const parsedDirectives = parseDirectivesString(directivesRaw);
+    const parsedDirectives = parseDirectivesString(directivesRaw, policy);
     if (!parsedDirectives.ok) {
         return parsedDirectives;
     }
@@ -255,7 +291,8 @@ export function parseTransformPath(segments) {
 /**
  * Canonical string form of a directive set, so equivalent directive sets
  * (different key order, different float formatting) always map to the same
- * cache key. Order is fixed alphabetically by key: c, f, q, w.
+ * cache key. Order is fixed alphabetically by key: c, f, q, w, and crop is
+ * rounded by `roundCropRect`.
  */
 export function formatDirectives(directives) {
     if (directives.identity) {
@@ -263,7 +300,7 @@ export function formatDirectives(directives) {
     }
     const parts = [];
     if (directives.crop) {
-        const { x, y, w, h } = directives.crop;
+        const { x, y, w, h } = roundCropRect(directives.crop);
         parts.push(`c=${formatUnitFloat(x)}:${formatUnitFloat(y)}:${formatUnitFloat(w)}:${formatUnitFloat(h)}`);
     }
     if (directives.format !== undefined) {
@@ -282,3 +319,26 @@ export function formatDirectives(directives) {
     // empty directives segment.
     return parts.length > 0 ? parts.join(',') : IDENTITY_TRANSFORM_DIRECTIVE;
 }
+/**
+ * Parse transform-path segments and resolve them to the one spelling their
+ * output is stored under. The returned `directives` are parsed back from that
+ * canonical spelling, never taken from the request, so a transform computed
+ * from them always matches its key. A crop that rounds to zero extent has no
+ * canonical spelling and is rejected.
+ */
+export function canonicalizeTransformPath(segments, policy) {
+    const parsed = parseTransformPath(segments, policy);
+    if (!parsed.ok)
+        return parsed;
+    const canonicalSegments = [
+        formatDirectives(parsed.directives),
+        parsed.hash32,
+        `${parsed.slug}.${parsed.ext}`,
+    ];
+    const canonical = parseTransformPath(canonicalSegments, policy);
+    if (!canonical.ok) {
+        return err(`No valid form at ${CROP_PRECISION} crop decimals: ${canonical.error}`);
+    }
+    const canonicalPath = canonicalSegments.join('/');
+    return { ...canonical, canonicalPath, isCanonical: canonicalPath === segments.join('/') };
+}

package/dist/assets/transform.d.ts

@@ -1,9 +1,9 @@
 /**
  * The shared transform engine: applies a parsed `TransformDirectives` to source image bytes
  * with sharp. Server-only - never import this from client/editor code (kept in its own file,
- * separate from the dependency-free transform-directives.ts). Used by the dev-mode lazy
- * `/assets/t/*` emulation in api/assets.ts and, unchanged, by the prod transform Lambda
- * (packages/canopycms-cdk/lambda/asset-transform).
+ * separate from the dependency-free transform-directives.ts). Its one caller here is
+ * `storeTransform` (materialize.ts), which the raw route, `materialize-assets` and the lazy
+ * transform Lambda share.
  *
  * sharp is imported for its TYPES only and loaded on first use through `loadSharp()`
  * (sharp-loader.ts), so importing this module never loads libvips - see sharp-loader.ts for

package/dist/assets/transform.js

@@ -1,9 +1,9 @@
 /**
  * The shared transform engine: applies a parsed `TransformDirectives` to source image bytes
  * with sharp. Server-only - never import this from client/editor code (kept in its own file,
- * separate from the dependency-free transform-directives.ts). Used by the dev-mode lazy
- * `/assets/t/*` emulation in api/assets.ts and, unchanged, by the prod transform Lambda
- * (packages/canopycms-cdk/lambda/asset-transform).
+ * separate from the dependency-free transform-directives.ts). Its one caller here is
+ * `storeTransform` (materialize.ts), which the raw route, `materialize-assets` and the lazy
+ * transform Lambda share.
  *
  * sharp is imported for its TYPES only and loaded on first use through `loadSharp()`
  * (sharp-loader.ts), so importing this module never loads libvips - see sharp-loader.ts for
@@ -27,7 +27,12 @@ import { loadSharp } from './sharp-loader.js';
 import { MAX_ANIMATED_FRAMES, MAX_INPUT_PIXELS, } from './transform-directives.js';
 /** Raster formats the transform engine accepts as input. svg/pdf never reach here - they're served statically. */
 const ALLOWED_INPUT_EXTS = new Set(['png', 'jpg', 'jpeg', 'webp', 'gif']);
-/** Defensive cap on encoded output size - prevents cache-stuffing with giant re-encodes. */
+/**
+ * Cap on a resize's encoded output, against cache-stuffing with giant re-encodes. An identity
+ * (`orig`) is exempt: an asset has one, its input is bounded by the upload and pixel caps, and a
+ * noisy PNG over about 10 MiB re-encodes to at least its own size, so the cap would refuse an
+ * ordinary upload's `orig` and fail the release that references it.
+ */
 const MAX_OUTPUT_BYTES = 10 * 1024 * 1024;
 const CONTENT_TYPE_BY_FORMAT = {
     webp: 'image/webp',
@@ -154,9 +159,9 @@ export async function applyTransform(input, directives) {
         // `pages` value that EXCEEDS the source's actual page count makes sharp
         // throw ("bad page number") rather than clamping, so `MAX_ANIMATED_FRAMES`
         // can only be applied as `Math.min(totalPages, MAX_ANIMATED_FRAMES)`.
-        // `limitInputPixels` gates this probe exactly like it gates the real
-        // pipeline below - an oversized source throws here already, before any
-        // pixel buffer is ever allocated.
+        // `limitInputPixels` on this probe counts one frame, so an oversized still
+        // throws here; the load below counts every frame it reads, so an over-cap
+        // animation throws there (measured at the cap: at most about one frame's buffer).
         const probeMeta = await sharp(input.data, { limitInputPixels: MAX_INPUT_PIXELS }).metadata();
         const totalPages = probeMeta.pages ?? 1;
         const pagesToRead = Math.min(totalPages, MAX_ANIMATED_FRAMES);
@@ -178,7 +183,7 @@ export async function applyTransform(input, directives) {
             ? encode(pipeline, format, quality)
             : encodeSourceFormat(pipeline, sourceExt, quality);
         const data = await pipeline.toBuffer();
-        if (data.byteLength > MAX_OUTPUT_BYTES) {
+        if (!directives.identity && data.byteLength > MAX_OUTPUT_BYTES) {
             return {
                 ok: false,
                 status: 413,

package/dist/assets/types.d.ts

@@ -55,7 +55,12 @@ export interface AssetStore {
         data: Uint8Array;
         contentType: string;
     }): Promise<void>;
-    readOriginal(hash32: string): Promise<{
+    /**
+     * `ext` is where the original is expected (its meta's `ext`): that key is read first, and any
+     * `{hash32}.*` is looked for only on a miss. A hit needs no list permission; on S3 without
+     * `s3:ListBucket` a miss is a 403, which throws.
+     */
+    readOriginal(hash32: string, ext?: string): Promise<{
         data: Uint8Array;
         ext: string;
         contentType?: string;
@@ -66,8 +71,16 @@ export interface AssetStore {
         contentType: string;
         contentDisposition?: string;
         cacheControl?: string;
+        /** Object tags; bucket lifecycle rules can filter on them. */
+        tags?: Readonly<Record<string, string>>;
     }): Promise<void>;
     readPublicObject(key: string): Promise<PublicObject | null>;
+    /** Whether a public object exists at `key`, without reading its body. */
+    hasPublicObject(key: string): Promise<boolean>;
+    /** Every public object key under `prefix`, in the store's own pages. S3 only. */
+    listPublicObjectKeys?(prefix: string): AsyncIterable<string>;
+    /** A short-lived URL a browser can GET `key` from directly, or `null` if absent. S3 only. */
+    presignPublicObjectRead?(key: string): Promise<string | null>;
     putMetaIfAbsent(hash32: string, meta: AssetMeta): Promise<'created' | 'already-exists'>;
     getMeta(hash32: string): Promise<AssetMeta | null>;
     listMeta(input?: {

package/dist/auth/file-based-auth-cache.js

@@ -168,14 +168,13 @@ export async function writeAuthCacheSnapshot(cachePath, files) {
         await fs.rename(tmpPath, finalPath);
     }
     // The symlink target MUST be relative (the bare `snapshot-<ts>` basename),
-    // because writer and reader do not share a mount namespace: in prod the EC2
-    // worker writes through /mnt/efs/workspace/.cache while the CMS Lambda mounts
-    // the /workspace access point and reads the SAME directory as /mnt/efs/.cache.
-    // An absolute target recorded by one is a nonexistent path to the other, and
-    // `resolveActiveCacheDir`'s escape guard then falls back to the flat layout,
-    // where the worker never writes — leaving the Lambda a permanently empty
-    // cache. A relative target resolves against whichever cachePath the reader
-    // was given, so it is correct from both.
+    // because writer and reader are separate hosts (in prod, the EC2 worker and
+    // the CMS Lambda) that each mount EFS themselves, so nothing guarantees they
+    // reach this directory by the same path. An absolute target recorded by one
+    // can be a nonexistent path to the other, and `resolveActiveCacheDir`'s
+    // escape guard then falls back to the flat layout, where the worker never
+    // writes, leaving the reader a permanently empty cache. A relative target
+    // resolves against whichever cachePath the reader was given.
     const currentLink = path.join(cachePath, 'current');
     const tmpLink = path.join(cachePath, `current-${timestamp}`);
     await fs.symlink(path.basename(snapshotDir), tmpLink);

package/dist/authorization/content.d.ts

@@ -6,12 +6,13 @@ import type { BranchContext } from '../types.js';
 import type { PermissionLevel } from '../config/index.js';
 import type { CanopyUser } from '../user.js';
 import type { ContentAccessResult, ContentAccessDeps } from './types.js';
-import type { PhysicalPath } from '../paths/types.js';
+import type { LogicalPath } from '../paths/types.js';
 /**
  * A bound content-access checker: evaluates a single path/level synchronously
  * against permissions that were already loaded when the checker was created.
+ * The path is the entry's logical path (see `checkPathAccess`).
  */
-export type ContentAccessChecker = (relativePath: PhysicalPath, level: PermissionLevel) => ContentAccessResult;
+export type ContentAccessChecker = (logicalPath: LogicalPath, level: PermissionLevel) => ContentAccessResult;
 /**
  * Resolve the request-constant work once -- branch access, the
  * settings/permissions root and the path-permission rules, all identical for a
@@ -26,5 +27,5 @@ export declare function createContentAccessChecker(deps: ContentAccessDeps, cont
  * Single-path check; loads the path permissions from the branch root per call.
  * @internal Exported for tests.
  */
-export declare function checkContentAccess(deps: ContentAccessDeps, context: BranchContext, branchRoot: string, relativePath: PhysicalPath, user: CanopyUser, level: PermissionLevel): Promise<ContentAccessResult>;
-export declare function createCheckContentAccess(deps: ContentAccessDeps): (context: BranchContext, branchRoot: string, relativePath: PhysicalPath, user: CanopyUser, level: PermissionLevel) => Promise<ContentAccessResult>;
+export declare function checkContentAccess(deps: ContentAccessDeps, context: BranchContext, branchRoot: string, logicalPath: LogicalPath, user: CanopyUser, level: PermissionLevel): Promise<ContentAccessResult>;
+export declare function createCheckContentAccess(deps: ContentAccessDeps): (context: BranchContext, branchRoot: string, logicalPath: LogicalPath, user: CanopyUser, level: PermissionLevel) => Promise<ContentAccessResult>;

package/dist/authorization/content.js

@@ -28,9 +28,9 @@ export async function createContentAccessChecker(deps, context, branchRoot, user
     }
     const rules = await deps.loadPathPermissions(permissionsRoot, deps.mode);
     const pathChecker = createCheckPathAccess(rules, deps.defaultPathAccess);
-    return (relativePath, level) => {
+    return (logicalPath, level) => {
         const path = pathChecker({
-            relativePath,
+            logicalPath,
             user,
             level,
         });
@@ -45,10 +45,10 @@ export async function createContentAccessChecker(deps, context, branchRoot, user
  * Single-path check; loads the path permissions from the branch root per call.
  * @internal Exported for tests.
  */
-export async function checkContentAccess(deps, context, branchRoot, relativePath, user, level) {
+export async function checkContentAccess(deps, context, branchRoot, logicalPath, user, level) {
     const check = await createContentAccessChecker(deps, context, branchRoot, user);
-    return check(relativePath, level);
+    return check(logicalPath, level);
 }
 export function createCheckContentAccess(deps) {
-    return (context, branchRoot, relativePath, user, level) => checkContentAccess(deps, context, branchRoot, relativePath, user, level);
+    return (context, branchRoot, logicalPath, user, level) => checkContentAccess(deps, context, branchRoot, logicalPath, user, level);
 }

package/dist/authorization/path.d.ts

@@ -1,7 +1,7 @@
 import type { PathPermission, DefaultPathAccess, PermissionLevel } from '../config/index.js';
 import type { CanopyUser } from '../user.js';
 import type { PathPermissionResult } from './types.js';
-import type { PhysicalPath } from '../paths/types.js';
+import type { LogicalPath } from '../paths/types.js';
 /**
  * Resolve `defaultPathAccess` to an 'allow'/'deny' verdict for one permission
  * level. String form applies to every level; object form looks up the level,
@@ -11,19 +11,24 @@ import type { PhysicalPath } from '../paths/types.js';
  */
 export declare function resolveDefaultPathAccess(defaultAccess: DefaultPathAccess, level: PermissionLevel): 'allow' | 'deny';
 /**
- * Evaluate access for a relative path against config-defined rules.
- * Uses defaultAccess when no rule matches. First matching rule wins.
+ * Evaluate access for a path against config-defined rules. First matching rule wins;
+ * defaultAccess applies when none matches.
+ *
+ * Rule globs and the checked path are both LOGICAL paths: content-root-prefixed and
+ * id-free, the space the Permission Manager writes rules in. An entry's logical path is
+ * `<collection logical path>/<slug>` (`entryLogicalPath`), e.g. `content/blog/my-post`, never
+ * its on-disk `content/blog.<id>/post.my-post.<id>.json`.
  * @internal Exported for tests.
  */
-export declare function checkPathAccess({ rules, relativePath, user, defaultAccess, level, }: {
+export declare function checkPathAccess({ rules, logicalPath, user, defaultAccess, level, }: {
     rules: PathPermission[];
-    relativePath: PhysicalPath;
+    logicalPath: LogicalPath;
     user: CanopyUser;
     defaultAccess: DefaultPathAccess;
     level: PermissionLevel;
 }): PathPermissionResult;
 export declare function createCheckPathAccess(rules: PathPermission[], defaultAccess: DefaultPathAccess): (input: {
-    relativePath: PhysicalPath;
+    logicalPath: LogicalPath;
     user: CanopyUser;
     level: PermissionLevel;
 }) => PathPermissionResult;

package/dist/authorization/path.js

@@ -5,8 +5,8 @@ function normalize(p) {
     const normalized = p.split(path.sep).join('/');
     return normalized.replace(/^\.?\/*/, '');
 }
-function matchesRule(rule, relativePath) {
-    return minimatch(relativePath, rule.path, { dot: true });
+function matchesRule(rule, logicalPath) {
+    return minimatch(logicalPath, rule.path, { dot: true });
 }
 function isAllowedByTarget(target, user) {
     const hasUserConstraint = !!target.allowedUsers?.length;
@@ -32,12 +32,17 @@ export function resolveDefaultPathAccess(defaultAccess, level) {
     return defaultAccess[level] ?? 'deny';
 }
 /**
- * Evaluate access for a relative path against config-defined rules.
- * Uses defaultAccess when no rule matches. First matching rule wins.
+ * Evaluate access for a path against config-defined rules. First matching rule wins;
+ * defaultAccess applies when none matches.
+ *
+ * Rule globs and the checked path are both LOGICAL paths: content-root-prefixed and
+ * id-free, the space the Permission Manager writes rules in. An entry's logical path is
+ * `<collection logical path>/<slug>` (`entryLogicalPath`), e.g. `content/blog/my-post`, never
+ * its on-disk `content/blog.<id>/post.my-post.<id>.json`.
  * @internal Exported for tests.
  */
-export function checkPathAccess({ rules, relativePath, user, defaultAccess, level, }) {
-    const normalizedPath = normalize(relativePath);
+export function checkPathAccess({ rules, logicalPath, user, defaultAccess, level, }) {
+    const normalizedPath = normalize(logicalPath);
     // Only Admins bypass all path permissions
     if (isAdmin(user.groups)) {
         return { allowed: true, reason: 'admin' };

package/dist/authorization/types.d.ts

@@ -1,6 +1,6 @@
 /**
- * A path used in permission rules, e.g. "content/posts".
- * SECURITY CRITICAL: always validated to prevent path traversal.
+ * A logical-path glob used in permission rules, e.g. "content/posts/**" (see
+ * `PathPermission.path`). SECURITY CRITICAL: always validated to prevent path traversal.
  */
 export type PermissionPath = string & {
     readonly __brand: 'PermissionPath';

package/dist/branch-health.d.ts

@@ -6,13 +6,19 @@ import { type DuplicateContentId } from './content-id-index.js';
  * Without it two stuck states have no in-product recovery, and prod admins have
  * no filesystem access to see them: a branch dir whose `.canopy-meta/branch.json`
  * is corrupt (the registry drops it silently) and an orphan dir with no
- * `branch.json` at all (a partial delete crash — see `api/branch.ts`).
+ * `branch.json` at all (a clone or delete killed in place, until the worker
+ * quarantines it — see branch-provisioning.ts).
  *
  * `scanBranchHealth` mirrors the registry's own directory-listing rules (skip
  * non-directories and dot-prefixed names) so the two never disagree about what
  * counts as missing.
  */
 type BranchHealthKind = 'healthy' | 'corrupt-metadata' | 'orphan';
+/**
+ * An orphan younger than this may still be a clone in progress: admin purge refuses it and the
+ * worker does not quarantine it. Corrupt-metadata dirs are exempt.
+ */
+export declare const ORPHAN_YOUTH_THRESHOLD_MS: number;
 export interface BranchHealthEntry {
     dirName: string;
     kind: BranchHealthKind;

package/dist/branch-health.js

@@ -5,16 +5,21 @@ import { ContentIdIndex } from './content-id-index.js';
 import { sanitizeBranchName } from './paths/branch-name.js';
 import { getErrorMessage, isNodeError, isNotFoundError } from './utils/error.js';
 import { isRebaseInProgress } from './utils/git.js';
+import { branchProvisioningLockName } from './utils/provisioning-lock.js';
 /**
- * The provisioning lock marker's path for a branch directory, matching what
- * `branch-workspace.ts`'s `ensureGitWorkspace()` passes exactly.
+ * An orphan younger than this may still be a clone in progress: admin purge refuses it and the
+ * worker does not quarantine it. Corrupt-metadata dirs are exempt.
+ */
+export const ORPHAN_YOUTH_THRESHOLD_MS = 15 * 60_000;
+/**
+ * The provisioning lock marker's path for a branch directory.
  *
  * `acquireProvisioningLock` passes the name as `lockfilePath`, overriding
  * proper-lockfile's default `${target}.lock`, so the marker (a mkdir-based
  * directory) sits at exactly this path — no extra `.lock` suffix.
  */
 function provisioningLockPath(baseRoot, dirName) {
-    return path.join(baseRoot, `.${dirName}.init.lock`);
+    return path.join(baseRoot, branchProvisioningLockName(dirName));
 }
 /** Stat the provisioning lock marker, if present. Never throws. */
 async function readProvisioningLock(baseRoot, dirName) {

package/dist/branch-metadata.d.ts

@@ -63,16 +63,16 @@ export declare class BranchMetadataFileManager {
      * entry with no clone behind it. It runs BEFORE the lock stack so a doomed
      * save fails fast instead of paying for a lock.
      *
-     * Accepted residual window: a save that passes the check can still race a
-     * `rm` that starts moments later and is mid-flight when the write lands.
-     * Closing that needs a tombstone OUTSIDE the tree being removed, and the
-     * lockfile taken next lives INSIDE `branchRoot`, so it can promise no more
-     * than "the directory existed a moment ago".
+     * A save that passes the check just before a delete still cannot write: the
+     * delete renames the tree away under the same lockfile, and that lockfile
+     * creates only its own directory (`withOccFileLock`), so the save fails there.
      */
     save(incoming: BranchMetadataUpdate): Promise<BranchMetadataFile>;
     /** Invalidate the registry cache so the next list() regenerates. */
     private invalidateRegistry;
 }
+/** The branch.json a brand-new branch starts with: {@link mergeBranchMetadata} over nothing. */
+export declare function buildInitialBranchMetadata(incoming: BranchMetadataUpdate, now?: string): BranchMetadataFile;
 /**
  * Fields save() accepts. `createdBy` applies on creation only and is ignored
  * once metadata exists; createdAt/updatedAt are managed here, not by callers.

package/dist/branch-metadata.js

@@ -101,11 +101,9 @@ export class BranchMetadataFileManager {
      * entry with no clone behind it. It runs BEFORE the lock stack so a doomed
      * save fails fast instead of paying for a lock.
      *
-     * Accepted residual window: a save that passes the check can still race a
-     * `rm` that starts moments later and is mid-flight when the write lands.
-     * Closing that needs a tombstone OUTSIDE the tree being removed, and the
-     * lockfile taken next lives INSIDE `branchRoot`, so it can promise no more
-     * than "the directory existed a moment ago".
+     * A save that passes the check just before a delete still cannot write: the
+     * delete renames the tree away under the same lockfile, and that lockfile
+     * creates only its own directory (`withOccFileLock`), so the save fails there.
      */
     async save(incoming) {
         try {
@@ -121,37 +119,7 @@ export class BranchMetadataFileManager {
         try {
             saved = await withLock(this.filePath, () => withOccFileLock(this.filePath, () => withOccRetry(async () => {
                 const { meta: existing, version } = await this.load();
-                const now = new Date().toISOString();
-                const defaults = {
-                    name: 'unknown',
-                    status: 'editing',
-                    access: {},
-                    createdBy: 'unknown',
-                    createdAt: now,
-                    updatedAt: now,
-                };
-                const merged = {
-                    schemaVersion: CURRENT_SCHEMA_VERSION,
-                    version: version ?? 0,
-                    branch: {
-                        ...defaults,
-                        ...existing?.branch,
-                        ...incoming.branch,
-                        access: {
-                            ...existing?.branch?.access,
-                            ...incoming.branch?.access,
-                        },
-                        // Immutable after creation
-                        createdBy: existing?.branch.createdBy ?? incoming.branch?.createdBy ?? defaults.createdBy,
-                        createdAt: existing?.branch.createdAt ?? defaults.createdAt,
-                        // Fork point is recorded once at creation; later saves must not move it
-                        baseBranch: existing?.branch.baseBranch ?? incoming.branch?.baseBranch,
-                        // Always stamped fresh; the spreads above would otherwise let
-                        // the creation-time value win forever, freezing the timestamp
-                        // the editor's Branches panel sorts and displays by
-                        updatedAt: now,
-                    },
-                };
+                const merged = mergeBranchMetadata(existing, version, incoming);
                 const written = await this.write(merged, version);
                 merged.version = written.version;
                 merged.writeId = written.writeId;
@@ -178,6 +146,46 @@ export class BranchMetadataFileManager {
         await registry.invalidate();
     }
 }
+/**
+ * The branch.json that {@link BranchMetadataFileManager.save} writes for `incoming` over
+ * `existing`. Pure, so a staged workspace's first branch.json (branch-provisioning.ts) is built by
+ * the same rules as a save and the two cannot drift.
+ */
+function mergeBranchMetadata(existing, version, incoming, now = new Date().toISOString()) {
+    const defaults = {
+        name: 'unknown',
+        status: 'editing',
+        access: {},
+        createdBy: 'unknown',
+        createdAt: now,
+        updatedAt: now,
+    };
+    return {
+        schemaVersion: CURRENT_SCHEMA_VERSION,
+        version: version ?? 0,
+        branch: {
+            ...defaults,
+            ...existing?.branch,
+            ...incoming.branch,
+            access: {
+                ...existing?.branch?.access,
+                ...incoming.branch?.access,
+            },
+            // Immutable after creation
+            createdBy: existing?.branch.createdBy ?? incoming.branch?.createdBy ?? defaults.createdBy,
+            createdAt: existing?.branch.createdAt ?? defaults.createdAt,
+            // Fork point is recorded once at creation; later saves must not move it
+            baseBranch: existing?.branch.baseBranch ?? incoming.branch?.baseBranch,
+            // Always stamped fresh; the spreads above would otherwise let the creation-time value win
+            // forever, freezing the timestamp the editor's Branches panel sorts and displays by
+            updatedAt: now,
+        },
+    };
+}
+/** The branch.json a brand-new branch starts with: {@link mergeBranchMetadata} over nothing. */
+export function buildInitialBranchMetadata(incoming, now) {
+    return mergeBranchMetadata(null, null, incoming, now);
+}
 /**
  * The metadata update for archiving a branch whose PR merged. Shared by the
  * worker's merge-poll (CmsWorker.pollMergeState) and the manual markAsMerged