canopycms 0.0.67 → 0.0.68-int.101

package/dist/assets/store-s3.js

@@ -1,16 +1,19 @@
 /**
  * S3-backed AssetStore. Same bucket-prefix layout as LocalAssetStore (see
  * keys.ts). Assumes an EXISTING content bucket (versioning/SSE/replication
- * already configured by the site's CDK stack) — this store only ever reads
- * and writes objects under the five asset prefixes.
+ * already configured by the site's CDK stack). It reads and writes under the
+ * five asset prefixes, plus a caller's output prefix for `copyPublicObject`.
  */
 import { randomUUID } from 'node:crypto';
-import { DeleteObjectCommand, GetObjectCommand, ListObjectsV2Command, PutObjectCommand, S3Client, } from '@aws-sdk/client-s3';
+import { CopyObjectCommand, DeleteObjectCommand, GetObjectCommand, HeadObjectCommand, ListObjectsV2Command, PutObjectCommand, S3Client, paginateListObjectsV2, } from '@aws-sdk/client-s3';
 import { createPresignedPost } from '@aws-sdk/s3-presigned-post';
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
 import { isHttpUrlOrSameOriginPath } from '../utils/sanitize-href.js';
 import { ASSET_PREFIXES, createKeyBuilders } from './keys.js';
 const DEFAULT_MAX_UPLOAD_BYTES = 50 * 1024 * 1024;
 const PRESIGN_EXPIRY_SECONDS = 15 * 60;
+/** A presigned read is followed by the browser at once; it is never stored or cached. */
+const PRESIGNED_READ_EXPIRY_SECONDS = 5 * 60;
 function matchesAwsError(err, name, httpStatusCode) {
     if (!(err instanceof Error))
         return false;
@@ -18,7 +21,20 @@ function matchesAwsError(err, name, httpStatusCode) {
     return shaped.name === name || shaped.$metadata?.httpStatusCode === httpStatusCode;
 }
 const isPreconditionFailed = (err) => matchesAwsError(err, 'PreconditionFailed', 412);
-const isNoSuchKey = (err) => matchesAwsError(err, 'NoSuchKey', 404);
+/**
+ * S3's 409 for a conditional write racing another write to the same key that is still in flight.
+ * Matched by name only: a 409 is also `OperationAborted`, which is not this.
+ */
+const isConditionalRequestConflict = (err) => err instanceof Error && err.name === 'ConditionalRequestConflict';
+/** At most 4 attempts and under 1.75 s of waiting; a race still unresolved after that throws the 409. */
+const CONFLICT_ATTEMPTS = 4;
+const CONFLICT_BASE_DELAY_MS = 250;
+/**
+ * A missing key, never a missing bucket: S3 answers both with 404, and only a GET's error code names
+ * which. A HEAD's 404 has no body, so `hasPublicObject` reads either as absent; a caller that must
+ * tell them apart follows with a GET (assets/materialize.ts does).
+ */
+const isNoSuchKey = (err) => matchesAwsError(err, 'NoSuchKey', 404) && err.name !== 'NoSuchBucket';
 export class S3AssetStore {
     constructor(options) {
         this.capabilities = { directUpload: true };
@@ -35,6 +51,38 @@ export class S3AssetStore {
         const prefixes = options.prefixes ?? ASSET_PREFIXES;
         this.keys = createKeyBuilders(prefixes);
         this.stagingPrefix = `${prefixes.staging}/`;
+        this.sleep =
+            options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    }
+    /**
+     * Sends one create-only request (`IfNoneMatch: '*'`), so S3 answers a taken key with 412. A
+     * `ConditionalRequestConflict` is retried here, the only retry layer for it, so a caller with no
+     * retry of its own (the lazy transform Lambda, finalize) ends in one of the two results.
+     *
+     * With `retriedIsCreated`, a 412 after any error the SDK had already retried counts as
+     * `created`: one of those attempts may have committed and lost its response. Public objects use
+     * it; meta does not, since a meta `already-exists` sends finalize to read the stored winner.
+     */
+    async createIfAbsent(send, options = {}) {
+        let sdkRetried = false;
+        for (let attempt = 1;; attempt++) {
+            try {
+                await send();
+                return 'created';
+            }
+            catch (err) {
+                sdkRetried ||= (err.$metadata?.attempts ?? 1) > 1;
+                if (isPreconditionFailed(err)) {
+                    return options.retriedIsCreated && sdkRetried ? 'created' : 'already-exists';
+                }
+                if (!isConditionalRequestConflict(err) || attempt >= CONFLICT_ATTEMPTS)
+                    throw err;
+                await this.sleep(CONFLICT_BASE_DELAY_MS * 2 ** (attempt - 1) * (0.5 + Math.random() / 2));
+            }
+        }
+    }
+    putIfAbsent(input, options = {}) {
+        return this.createIfAbsent(() => this.client.send(new PutObjectCommand({ ...input, Bucket: this.bucket, IfNoneMatch: '*' })), options);
     }
     /**
      * Staging methods accept caller-influenced keys (finalize receives the key
@@ -90,14 +138,19 @@ export class S3AssetStore {
         await this.client.send(new DeleteObjectCommand({ Bucket: this.bucket, Key: key }));
     }
     async putOriginal(input) {
-        await this.client.send(new PutObjectCommand({
-            Bucket: this.bucket,
+        return this.putIfAbsent({
             Key: this.keys.originalKey(input.hash32, input.ext),
             Body: input.data,
             ContentType: input.contentType,
-        }));
+        });
     }
-    async readOriginal(hash32) {
+    async readOriginal(hash32, ext) {
+        if (ext !== undefined) {
+            const direct = await this.getObject(this.keys.originalKey(hash32, ext));
+            const data = await direct?.Body?.transformToByteArray();
+            if (data)
+                return { data, ext, contentType: direct?.ContentType };
+        }
         const prefix = this.keys.originalPrefix(hash32);
         const listed = await this.client.send(new ListObjectsV2Command({ Bucket: this.bucket, Prefix: prefix, MaxKeys: 1 }));
         const foundKey = listed.Contents?.[0]?.Key;
@@ -112,14 +165,45 @@ export class S3AssetStore {
         return { data, ext: foundKey.slice(prefix.length), contentType: result.ContentType };
     }
     async putPublicObject(input) {
-        await this.client.send(new PutObjectCommand({
-            Bucket: this.bucket,
+        // `encodeURIComponent` writes a space as `%20`, which reads the same to any decoder;
+        // URLSearchParams writes `+`.
+        const tagging = Object.entries(input.tags ?? {})
+            .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`)
+            .join('&');
+        return this.putIfAbsent({
             Key: input.key,
             Body: input.data,
             ContentType: input.contentType,
             ContentDisposition: input.contentDisposition,
             CacheControl: input.cacheControl,
-        }));
+            Tagging: tagging || undefined,
+        }, { retriedIsCreated: true });
+    }
+    /**
+     * A server-side CopyObject. S3 URL-decodes `CopySource`, and keys hold `=`, `,` and `:`, so each
+     * segment is encoded and the `/` between them is not. `MetadataDirective: 'COPY'` keeps the
+     * source's Content-Type, Cache-Control and Content-Disposition; `TaggingDirective: 'REPLACE'`
+     * with no `Tagging` leaves the copy untagged and needs no tagging permission, even from a
+     * lazy-tagged source; `COPY` would need `s3:GetObjectTagging` and `s3:PutObjectTagging`.
+     */
+    async copyPublicObject(sourceKey, destKey) {
+        const copySource = `${this.bucket}/${sourceKey.split('/').map(encodeURIComponent).join('/')}`;
+        try {
+            return await this.createIfAbsent(() => this.client.send(new CopyObjectCommand({
+                Bucket: this.bucket,
+                Key: destKey,
+                CopySource: copySource,
+                IfNoneMatch: '*',
+                MetadataDirective: 'COPY',
+                TaggingDirective: 'REPLACE',
+            })), { retriedIsCreated: true });
+        }
+        catch (err) {
+            // By name alone: a copy's error always carries its code, and a missing bucket is a 404 too.
+            if (err instanceof Error && err.name === 'NoSuchKey')
+                return 'source-missing';
+            throw err;
+        }
     }
     async readPublicObject(key) {
         const result = await this.getObject(key);
@@ -135,23 +219,45 @@ export class S3AssetStore {
             cacheControl: result.CacheControl,
         };
     }
-    async putMetaIfAbsent(hash32, meta) {
+    /**
+     * A HEAD. S3 answers a missing key with 403, not 404, unless the caller may `s3:ListBucket`,
+     * so a role without it sees an error here rather than `false`.
+     */
+    async hasPublicObject(key) {
         try {
-            await this.client.send(new PutObjectCommand({
-                Bucket: this.bucket,
-                Key: this.keys.metaKey(hash32),
-                Body: JSON.stringify(meta),
-                ContentType: 'application/json',
-                IfNoneMatch: '*',
-            }));
-            return 'created';
+            await this.client.send(new HeadObjectCommand({ Bucket: this.bucket, Key: key }));
+            return true;
         }
         catch (err) {
-            if (isPreconditionFailed(err))
-                return 'already-exists';
+            if (isNoSuchKey(err))
+                return false;
             throw err;
         }
     }
+    async *listPublicObjectKeys(prefix) {
+        const pages = paginateListObjectsV2({ client: this.client }, { Bucket: this.bucket, Prefix: prefix });
+        for await (const page of pages) {
+            for (const object of page.Contents ?? []) {
+                if (object.Key)
+                    yield object.Key;
+            }
+        }
+    }
+    /** HEADs first: signing is local and succeeds for a missing key too. */
+    async presignPublicObjectRead(key) {
+        if (!(await this.hasPublicObject(key)))
+            return null;
+        return getSignedUrl(this.client, new GetObjectCommand({ Bucket: this.bucket, Key: key }), {
+            expiresIn: PRESIGNED_READ_EXPIRY_SECONDS,
+        });
+    }
+    async putMetaIfAbsent(hash32, meta) {
+        return this.putIfAbsent({
+            Key: this.keys.metaKey(hash32),
+            Body: JSON.stringify(meta),
+            ContentType: 'application/json',
+        });
+    }
     async getMeta(hash32) {
         const bytes = await this.getObjectBytes(this.keys.metaKey(hash32));
         if (!bytes)

package/dist/assets/transform-directives.d.ts

@@ -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)
@@ -56,6 +55,18 @@ export type ParseTransformPathResult = ({
     readonly ok: false;
     readonly error: string;
 };
+/**
+ * Which widths a transform path accepts. The policy only narrows what parses; a width that parses
+ * under both has the same canonical spelling under both.
+ *
+ * - `allowlist`: multiples of 160 in [160, 4096], plus the small rungs 32, 48, 64, 96 and 128. For
+ *   the opt-in anonymous on-demand path, where every accepted width is a new stored object an
+ *   anonymous caller can mint.
+ * - `any`: any integer in [1, 8192]. For every path where the URLs come from site code or a
+ *   signed-in editor: the authenticated route, `assetUrl`/`assetSrcSet`, the collector and the
+ *   materializer.
+ */
+export type TransformWidthPolicy = 'allowlist' | 'any';
 /**
  * Decompression-bomb cap: the max `width * height` (post-decode pixel count)
  * any raster the pipeline handles may have - checked both at upload finalize
@@ -63,10 +74,12 @@ export type ParseTransformPathResult = ({
  * 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 declare const MAX_INPUT_PIXELS: number;
 /**
@@ -87,8 +100,8 @@ export declare const MAX_INPUT_PIXELS: number;
  * ignore) rather than by two constants that happen to match today.
  */
 export declare const MAX_ANIMATED_FRAMES = 60;
-/** True if `width` is on the allowlist: a multiple of 160 in [160, 4096]. */
-export declare function isAllowedTransformWidth(width: number): boolean;
+/** True if `policy` accepts `width`; see `TransformWidthPolicy`. */
+export declare function isAllowedTransformWidth(width: number, policy: TransformWidthPolicy): boolean;
 /**
  * True when x, y, w, h describe a valid normalized crop rect: all four values
  * finite and in [0,1], w and h strictly positive, and the rect fits within
@@ -98,16 +111,42 @@ export declare function isAllowedTransformWidth(width: number): boolean;
  * identical constraints.
  */
 export declare function isValidCropRect(x: number, y: number, w: number, h: number): boolean;
+/**
+ * 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 declare function roundCropRect(rect: CropRect): CropRect;
 /**
  * Parse the three path segments after the `assets/t/` prefix:
  * `[directivesRaw, hash32, "{slug}.{ext}"]`. The raw route strips the
  * `assets/t/` prefix and splits the remaining key by `/` before calling this.
  */
-export declare function parseTransformPath(segments: readonly string[]): ParseTransformPathResult;
+export declare function parseTransformPath(segments: readonly string[], policy: TransformWidthPolicy): ParseTransformPathResult;
 /**
  * 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 declare function formatDirectives(directives: TransformDirectives): string;
+export type CanonicalTransformPathResult = ({
+    readonly ok: true;
+    /** `{directives}/{hash32}/{slug}.{ext}` in canonical form, without the `assets/t/` prefix. */
+    readonly canonicalPath: string;
+    /** True when the requested segments already were `canonicalPath`, byte for byte. */
+    readonly isCanonical: boolean;
+} & ParsedTransformPath) | {
+    readonly ok: false;
+    readonly error: string;
+};
+/**
+ * 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 declare function canonicalizeTransformPath(segments: readonly string[], policy: TransformWidthPolicy): CanonicalTransformPathResult;
 export {};

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,