canopycms 0.0.67 → 0.0.68-int.101

package/dist/assets/materialize.js

@@ -0,0 +1,402 @@
+/**
+ * Writing transform outputs into the store. Server-only.
+ *
+ * `storeTransform` computes one key and is shared by the authenticated raw route
+ * (api/assets.ts), `materializeAssets` (the batch run that writes every key a build references
+ * before that build is released) and canopycms-cdk's lazy transform Lambda.
+ */
+import { getErrorMessage, isNodeError } from '../utils/error.js';
+import { ASSET_PREFIXES } from './asset-prefixes.js';
+import { loadSharp } from './sharp-loader.js';
+import { applyTransform } from './transform.js';
+import { canonicalizeTransformPath } from './transform-directives.js';
+/** Every transform output is stored under a content-addressed key, so it never changes. */
+export const TRANSFORM_CACHE_CONTROL = 'public, max-age=31536000, immutable';
+/**
+ * The object tag on every derivative the lazy transform Lambda writes. Its bucket's `assets/t/`
+ * expiry filters on it, so what `materializeAssets` writes, which the Lambda's allowlist may refuse
+ * to recompute, is never expired. canopycms-cdk's `AssetSupport` copies these two strings as
+ * literals.
+ */
+export const LAZY_TRANSFORM_TAG = { key: 'canopy-transform', value: 'lazy' };
+/**
+ * Compute the transform `parsed` names from the asset's original and write it under `key`: the
+ * canonical key, or that key beneath an output prefix. `parsed` must come from
+ * `canonicalizeTransformPath`, so the stored pixels always match their key. A rejection is a fact
+ * about the asset or the URL and is never worth retrying; a thrown error belongs to the store or
+ * the environment. A 404's `error` names what was missing, so a caller answering a browser
+ * replaces it.
+ */
+export async function storeTransform(store, parsed, key, options = {}) {
+    const meta = await store.getMeta(parsed.hash32);
+    if (!meta) {
+        return { ok: false, status: 404, error: `Asset ${parsed.hash32} has no meta in the store` };
+    }
+    if (meta.kind !== 'raster') {
+        return { ok: false, status: 400, error: 'Not a raster asset - svg/pdf are served statically' };
+    }
+    // The slug is decorative in the URL but load-bearing in the stored key, so it must equal the
+    // asset's real slug — the parser only enforces `[a-z0-9-]+`, and any other string that passes
+    // it aliases the same image into a new cache key.
+    if (parsed.slug !== meta.slug) {
+        return {
+            ok: false,
+            status: 404,
+            error: `Slug '${parsed.slug}' is not asset ${parsed.hash32}'s slug '${meta.slug}'`,
+        };
+    }
+    // Without an explicit `f=`, the transform keeps the source format, so the URL's `{ext}` must be
+    // the source's real ext. The parser cannot check this: it does not know the source format.
+    const requestedFormat = parsed.directives.identity ? undefined : parsed.directives.format;
+    if (requestedFormat === undefined && parsed.ext !== meta.ext) {
+        return { ok: false, status: 400, error: 'Extension does not match the source format' };
+    }
+    const original = await store.readOriginal(parsed.hash32, meta.ext);
+    if (!original) {
+        return { ok: false, status: 404, error: `Asset ${parsed.hash32} has no original in the store` };
+    }
+    const transformed = await applyTransform({ data: original.data, ext: original.ext }, parsed.directives);
+    if (!transformed.ok) {
+        return { ok: false, status: transformed.status, error: transformed.error };
+    }
+    const stored = await store.putPublicObject({
+        key,
+        data: transformed.data,
+        contentType: transformed.contentType,
+        cacheControl: TRANSFORM_CACHE_CONTROL,
+        tags: options.tags,
+    });
+    return { ok: true, data: transformed.data, contentType: transformed.contentType, stored };
+}
+/** The `schemaVersion` of every `MaterializeReport`; a consumer gating on the JSON checks it. */
+export const MATERIALIZE_REPORT_SCHEMA_VERSION = 1;
+/** sharp cannot load in this process, so nothing missing can be produced here. */
+export class SharpUnavailableError extends Error {
+    constructor(cause) {
+        super(`sharp failed to load, so the missing transform outputs cannot be produced in this ` +
+            `environment: ${getErrorMessage(cause)}. Install sharp for this platform and rerun.`);
+        this.name = 'SharpUnavailableError';
+    }
+}
+/** `MaterializeOptions.outputPrefix` broke a rule of `assertValidOutputPrefix`; nothing was read or written. */
+export class InvalidOutputPrefixError extends Error {
+    constructor(prefix, reason) {
+        super(`Invalid output prefix ${JSON.stringify(prefix)}: ${reason}`);
+        this.name = 'InvalidOutputPrefixError';
+    }
+}
+const OUTPUT_PREFIX_SEGMENT_RE = /^[A-Za-z0-9._-]+$/;
+const CANOPY_PREFIX_SEGMENTS = Object.values(ASSET_PREFIXES).map((prefix) => prefix.split('/'));
+/**
+ * Throws `InvalidOutputPrefixError` unless `prefix` is relative, ends in `/`, and is a run of
+ * `[A-Za-z0-9._-]` segments, none empty, `.` or `..`, whose first segments are not a canopy
+ * prefix. Production trusts whatever is under its own prefixes, so a write beneath one is a write
+ * production serves. Compared by segment: `assets-x/` is accepted, `assets/x/` is not.
+ */
+export function assertValidOutputPrefix(prefix) {
+    const refuse = (reason) => {
+        throw new InvalidOutputPrefixError(prefix, reason);
+    };
+    if (prefix.startsWith('/'))
+        refuse('it must be relative, with no leading /');
+    if (!prefix.endsWith('/'))
+        refuse('it must end in /');
+    const segments = prefix.slice(0, -1).split('/');
+    for (const segment of segments) {
+        if (segment === '')
+            refuse('it has an empty segment');
+        if (segment === '.' || segment === '..')
+            refuse(`it has a ${segment} segment`);
+        if (!OUTPUT_PREFIX_SEGMENT_RE.test(segment)) {
+            refuse(`segment ${JSON.stringify(segment)} has a character outside [A-Za-z0-9._-]`);
+        }
+    }
+    const canopy = CANOPY_PREFIX_SEGMENTS.find((prefixSegments) => prefixSegments.every((segment, i) => segments[i] === segment));
+    if (canopy)
+        refuse(`it begins with the canopy prefix ${canopy.join('/')}/`);
+}
+const DEFAULT_CONCURRENCY = 8;
+const DEFAULT_TRANSFORM_CONCURRENCY = 2;
+// eslint-disable-next-line security/detect-non-literal-regexp -- built from a constant
+const STATIC_KEY_RE = new RegExp(`^${ASSET_PREFIXES.public}/[a-f0-9]{32}/[a-z0-9-]+\\.[a-z0-9]{1,10}$`);
+const DEFAULT_LIST_THRESHOLD = 100;
+const DEFAULT_ATTEMPTS = 3;
+const DEFAULT_BASE_DELAY_MS = 500;
+const TRANSIENT_NODE_CODES = new Set([
+    'ECONNRESET',
+    'ECONNREFUSED',
+    'ETIMEDOUT',
+    'EPIPE',
+    'EAI_AGAIN',
+    'EBUSY',
+    'EMFILE',
+]);
+const TRANSIENT_ERROR_NAMES = new Set([
+    'TimeoutError',
+    'RequestTimeout',
+    'RequestTimeoutException',
+    'SlowDown',
+    'Throttling',
+    'ThrottlingException',
+    'ServiceUnavailable',
+    'InternalError',
+]);
+/**
+ * @internal Exported for tests. Throttling, 5xx and dropped connections are transient. Any other
+ * 4xx (AccessDenied, NoSuchBucket) is a configuration fault that a retry only delays.
+ */
+export function isTransientStoreError(err) {
+    if (!(err instanceof Error))
+        return false;
+    if (isNodeError(err) && err.code && TRANSIENT_NODE_CODES.has(err.code))
+        return true;
+    const shaped = err;
+    if (shaped.$retryable)
+        return true;
+    if (TRANSIENT_ERROR_NAMES.has(err.name))
+        return true;
+    const status = shaped.$metadata?.httpStatusCode;
+    return status !== undefined && (status === 429 || status >= 500);
+}
+/** Run `fn` over `items` with at most `limit` in flight. `fn` must not reject. */
+async function forEachBounded(items, limit, fn) {
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length) {
+            const item = items[next++];
+            await fn(item);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+}
+/**
+ * Make every referenced transform key exist in `store`, and check every static key does. A key
+ * already stored is left alone:
+ * keys are content-addressed, so an existing object is the right one. sharp is loaded only when
+ * something must be transformed, and a sharp that cannot load throws `SharpUnavailableError` rather
+ * than failing each key. An invalid `outputPrefix` throws `InvalidOutputPrefixError` first.
+ */
+export async function materializeAssets(options) {
+    const { store, outputPrefix } = options;
+    if (outputPrefix !== undefined)
+        assertValidOutputPrefix(outputPrefix);
+    const destOf = (key) => (outputPrefix ?? '') + key;
+    const concurrency = Math.max(1, options.concurrency ?? DEFAULT_CONCURRENCY);
+    const transformConcurrency = Math.max(1, options.transformConcurrency ?? DEFAULT_TRANSFORM_CONCURRENCY);
+    const listThreshold = options.listThreshold ?? DEFAULT_LIST_THRESHOLD;
+    const attempts = Math.max(1, options.attempts ?? DEFAULT_ATTEMPTS);
+    const baseDelayMs = options.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const withRetry = async (operation) => {
+        for (let attempt = 1;; attempt++) {
+            try {
+                return await operation();
+            }
+            catch (err) {
+                if (attempt >= attempts || !isTransientStoreError(err))
+                    throw err;
+                await sleep(baseDelayMs * 2 ** (attempt - 1) * (1 + Math.random()));
+            }
+        }
+    };
+    const references = new Map();
+    const staticKeys = new Set((options.statics ?? []).map((target) => target.key));
+    for (const target of [...options.targets, ...(options.statics ?? [])]) {
+        const entry = references.get(target.key) ?? { routes: new Set(), files: new Set() };
+        target.routes.forEach((route) => entry.routes.add(route));
+        target.files.forEach((file) => entry.files.add(file));
+        references.set(target.key, entry);
+    }
+    const outcomes = new Map();
+    const fail = (key, failure, error) => outcomes.set(key, { status: 'failed', failure, error });
+    // The refs file is an editable file on disk, so every key is re-validated here.
+    const transformPrefix = `${ASSET_PREFIXES.transform}/`;
+    const valid = [];
+    const validStatics = [];
+    for (const key of references.keys()) {
+        if (staticKeys.has(key)) {
+            if (STATIC_KEY_RE.test(key))
+                validStatics.push(key);
+            else
+                fail(key, 'content', 'Not a static asset key (expected assets/{hash32}/{slug}.{ext})');
+            continue;
+        }
+        if (!key.startsWith(transformPrefix)) {
+            fail(key, 'content', `Not a transform key (expected a ${transformPrefix} prefix)`);
+            continue;
+        }
+        const segments = key.slice(transformPrefix.length).split('/');
+        const canonical = canonicalizeTransformPath(segments, 'any');
+        if (!canonical.ok) {
+            fail(key, 'content', `Invalid transform key: ${canonical.error}`);
+        }
+        else if (!canonical.isCanonical) {
+            fail(key, 'content', `Not canonical; the stored key would be ${transformPrefix}${canonical.canonicalPath}`);
+        }
+        else {
+            valid.push({ key, directives: segments[0], parsed: canonical });
+        }
+    }
+    const byDirectives = new Map();
+    for (const target of valid) {
+        const group = byDirectives.get(target.directives) ?? [];
+        group.push(target);
+        byDirectives.set(target.directives, group);
+    }
+    const listOnce = async (prefix) => {
+        if (!store.listPublicObjectKeys)
+            return undefined;
+        const listKeys = store.listPublicObjectKeys.bind(store);
+        try {
+            return new Set(await withRetry(async () => {
+                const keys = [];
+                for await (const key of listKeys(prefix))
+                    keys.push(key);
+                return keys;
+            }));
+        }
+        catch {
+            // A listing that keeps failing costs only speed: its keys are HEADed instead, and each HEAD
+            // reports its own failure.
+            return undefined;
+        }
+    };
+    const listingsByDirectives = new Map();
+    if (store.listPublicObjectKeys) {
+        for (const [directives, group] of byDirectives) {
+            if (group.length < listThreshold)
+                continue;
+            const listPrefix = `${transformPrefix}${directives}/`;
+            const dest = await listOnce(destOf(listPrefix));
+            const needsCanonical = outputPrefix !== undefined && group.some((target) => !dest?.has(destOf(target.key)));
+            const canonical = needsCanonical ? await listOnce(listPrefix) : undefined;
+            listingsByDirectives.set(directives, { dest, canonical });
+        }
+    }
+    // Every presence check goes through here. Without an output prefix a key's destination is the
+    // key itself, so this is one listing lookup or HEAD and never `canonical`.
+    const resolvePresence = async (key, listings = {}) => {
+        const isStored = async (storeKey, listing) => listing ? listing.has(storeKey) : withRetry(() => store.hasPublicObject(storeKey));
+        const dest = destOf(key);
+        if (await isStored(dest, listings.dest))
+            return 'dest';
+        if (dest === key)
+            return 'absent';
+        return (await isStored(key, listings.canonical)) ? 'canonical' : 'absent';
+    };
+    const presence = new Map();
+    await forEachBounded(valid, concurrency, async (target) => {
+        try {
+            presence.set(target.key, await resolvePresence(target.key, listingsByDirectives.get(target.directives)));
+        }
+        catch (err) {
+            fail(target.key, 'store', `Existence check failed: ${getErrorMessage(err)}`);
+        }
+    });
+    await forEachBounded(validStatics, concurrency, async (key) => {
+        try {
+            let found = await resolvePresence(key);
+            // A HEAD cannot tell a missing key from a missing bucket, and a static key has no
+            // transform's meta read to tell them apart afterwards; a GET names which.
+            if (found === 'absent' && (await withRetry(() => store.readPublicObject(key))) !== null) {
+                found = destOf(key) === key ? 'dest' : 'canonical';
+            }
+            presence.set(key, found);
+        }
+        catch (err) {
+            fail(key, 'store', `Existence check failed: ${getErrorMessage(err)}`);
+        }
+    });
+    const toCopy = [];
+    for (const [key, found] of presence) {
+        if (found === 'dest')
+            outcomes.set(key, { status: 'existed' });
+        else if (found === 'canonical')
+            toCopy.push(key);
+    }
+    await forEachBounded(toCopy, concurrency, async (key) => {
+        try {
+            let tries = 0;
+            const copied = await withRetry(() => {
+                tries++;
+                return store.copyPublicObject(key, destOf(key));
+            });
+            if (copied === 'source-missing') {
+                presence.set(key, 'absent');
+            }
+            else {
+                // After a failed try, `already-exists` may be that try's own copy, as for a transform.
+                const copiedElsewhere = copied === 'already-exists' && tries === 1;
+                outcomes.set(key, { status: copiedElsewhere ? 'existed' : 'copied' });
+            }
+        }
+        catch (err) {
+            fail(key, 'store', `Copy failed: ${getErrorMessage(err)}`);
+        }
+    });
+    for (const key of validStatics) {
+        if (presence.get(key) === 'absent') {
+            fail(key, 'content', 'No stored object; an svg or pdf is written at upload only');
+        }
+    }
+    const missing = valid.filter((target) => presence.get(target.key) === 'absent');
+    if (missing.length > 0) {
+        try {
+            await loadSharp();
+        }
+        catch (err) {
+            throw new SharpUnavailableError(err);
+        }
+    }
+    await forEachBounded(missing, transformConcurrency, async (target) => {
+        try {
+            let tries = 0;
+            const result = await withRetry(() => {
+                tries++;
+                return storeTransform(store, target.parsed, destOf(target.key));
+            });
+            if (result.ok) {
+                // After a failed attempt, `already-exists` may be that attempt's own write, whose response
+                // was lost, so it counts as `created`: a release waiting on its `created` keys then waits
+                // on a key it may not have written, never skips one it did.
+                const createdElsewhere = result.stored === 'already-exists' && tries === 1;
+                outcomes.set(target.key, { status: createdElsewhere ? 'existed' : 'created' });
+            }
+            else {
+                fail(target.key, 'content', `${result.status}: ${result.error}`);
+            }
+        }
+        catch (err) {
+            fail(target.key, 'store', getErrorMessage(err));
+        }
+    });
+    const results = [...references.keys()].sort().map((key) => {
+        const refs = references.get(key);
+        const outcome = outcomes.get(key) ?? {
+            status: 'failed',
+            failure: 'store',
+            error: 'No outcome recorded',
+        };
+        return {
+            key,
+            routes: [...(refs?.routes ?? [])].sort(),
+            files: [...(refs?.files ?? [])].sort(),
+            ...outcome,
+        };
+    });
+    const count = (predicate) => results.filter(predicate).length;
+    return {
+        schemaVersion: MATERIALIZE_REPORT_SCHEMA_VERSION,
+        ...(outputPrefix !== undefined ? { outputPrefix } : {}),
+        summary: {
+            total: results.length,
+            existed: count((r) => r.status === 'existed'),
+            created: count((r) => r.status === 'created'),
+            copied: count((r) => r.status === 'copied'),
+            failed: count((r) => r.status === 'failed'),
+            contentFailures: count((r) => r.status === 'failed' && r.failure === 'content'),
+            storeFailures: count((r) => r.status === 'failed' && r.failure === 'store'),
+        },
+        results,
+    };
+}

package/dist/assets/store-local.d.ts

@@ -3,7 +3,7 @@
  * bucket-prefix layout as S3AssetStore (see keys.ts) so content behaves
  * identically across adapters.
  */
-import type { AssetMeta, AssetStore, BeginUploadInput, PublicObject, StagedUploadTarget } from './types.js';
+import type { AssetMeta, AssetStore, BeginUploadInput, CreateOnlyResult, PublicObject, StagedUploadTarget } from './types.js';
 export interface LocalAssetStoreOptions {
     /** Root directory. The five bucket prefixes are created as subdirectories under it. */
     root: string;
@@ -26,11 +26,20 @@ export declare class LocalAssetStore implements AssetStore {
      */
     private resolveKey;
     private headersSidecarPath;
-    private writeHeadersSidecar;
     private readHeadersSidecar;
     private readFileOrNull;
     private writeFile;
     private deleteFileIfPresent;
+    /** Link `tempPath` in at `filePath`; `false` when something is already there. */
+    private linkIfAbsent;
+    /**
+     * Create-only write of a blob and its headers sidecar. Each is written whole to a temp file, then
+     * `link()`ed into place, which fails with EEXIST rather than replacing (see docs/concurrency.md).
+     * The sidecar is linked first, so a reader never finds a blob without its headers. A sidecar
+     * already there was linked by an earlier writer of this key and is kept, as the blob is: the
+     * first writer's headers win, as on S3 (a static's Content-Disposition names its uploaded file).
+     */
+    private createExclusive;
     beginUpload(_input: BeginUploadInput): Promise<StagedUploadTarget>;
     /**
      * Staging methods accept caller-influenced keys (finalize receives the key
@@ -47,7 +56,8 @@ export declare class LocalAssetStore implements AssetStore {
         ext: string;
         data: Uint8Array;
         contentType: string;
-    }): Promise<void>;
+    }): Promise<CreateOnlyResult>;
+    /** Ignores the `ext` hint: a directory read costs nothing here and needs no permission. */
     readOriginal(hash32: string): Promise<{
         data: Uint8Array;
         ext: string;
@@ -59,8 +69,12 @@ export declare class LocalAssetStore implements AssetStore {
         contentType: string;
         contentDisposition?: string;
         cacheControl?: string;
-    }): Promise<void>;
+        /** Ignored: tags exist for bucket lifecycle rules, and a local store has none. */
+        tags?: Readonly<Record<string, string>>;
+    }): Promise<CreateOnlyResult>;
+    copyPublicObject(sourceKey: string, destKey: string): Promise<CreateOnlyResult | 'source-missing'>;
     readPublicObject(key: string): Promise<PublicObject | null>;
+    hasPublicObject(key: string): Promise<boolean>;
     /**
      * Atomic-exclusive create: opens with the `wx` flag so two concurrent
      * writers racing on the same hash32 have exactly one winner ('created')
@@ -69,7 +83,7 @@ export declare class LocalAssetStore implements AssetStore {
      * always clobbers the destination, which would let the second writer
      * silently overwrite the first instead of losing cleanly.
      */
-    putMetaIfAbsent(hash32: string, meta: AssetMeta): Promise<'created' | 'already-exists'>;
+    putMetaIfAbsent(hash32: string, meta: AssetMeta): Promise<CreateOnlyResult>;
     getMeta(hash32: string): Promise<AssetMeta | null>;
     listMeta(input?: {
         cursor?: string;

package/dist/assets/store-local.js

@@ -13,6 +13,13 @@ import { ASSET_PREFIXES, metaKey, originalKey, stagingKey } from './keys.js';
 const DEFAULT_MAX_UPLOAD_BYTES = 50 * 1024 * 1024;
 const DEFAULT_LIST_LIMIT = 24;
 const HEADERS_SIDECAR_SUFFIX = '.headers.json';
+/**
+ * Where create-only writes stage their bytes: under the root, so `link()` stays on one filesystem,
+ * and outside every prefix, so no read or listing of a prefix ever sees a partial file.
+ */
+const TEMP_DIR = '.asset-tmp';
+/** An original's file name after `{hash32}.`; a sidecar or any other name in the directory fails it. */
+const ORIGINAL_EXT_RE = /^[a-z0-9]+$/;
 export class LocalAssetStore {
     constructor(options) {
         this.capabilities = { directUpload: false };
@@ -39,9 +46,6 @@ export class LocalAssetStore {
     headersSidecarPath(filePath) {
         return `${filePath}${HEADERS_SIDECAR_SUFFIX}`;
     }
-    async writeHeadersSidecar(filePath, headers) {
-        await atomicWriteFile(this.headersSidecarPath(filePath), JSON.stringify(headers));
-    }
     async readHeadersSidecar(filePath) {
         try {
             const raw = await fs.readFile(this.headersSidecarPath(filePath), 'utf-8');
@@ -78,6 +82,44 @@ export class LocalAssetStore {
         // Best-effort sidecar cleanup; a missing sidecar is not an error.
         await fs.unlink(this.headersSidecarPath(filePath)).catch(() => { });
     }
+    /** Link `tempPath` in at `filePath`; `false` when something is already there. */
+    async linkIfAbsent(tempPath, filePath) {
+        try {
+            await fs.link(tempPath, filePath);
+            return true;
+        }
+        catch (err) {
+            if (isFileExistsError(err))
+                return false;
+            throw err;
+        }
+    }
+    /**
+     * Create-only write of a blob and its headers sidecar. Each is written whole to a temp file, then
+     * `link()`ed into place, which fails with EEXIST rather than replacing (see docs/concurrency.md).
+     * The sidecar is linked first, so a reader never finds a blob without its headers. A sidecar
+     * already there was linked by an earlier writer of this key and is kept, as the blob is: the
+     * first writer's headers win, as on S3 (a static's Content-Disposition names its uploaded file).
+     */
+    async createExclusive(key, data, headers) {
+        const filePath = this.resolveKey(key);
+        const tempDir = this.resolveKey(TEMP_DIR);
+        await Promise.all([
+            fs.mkdir(tempDir, { recursive: true }),
+            fs.mkdir(path.dirname(filePath), { recursive: true }),
+        ]);
+        const tempBlob = path.join(tempDir, randomUUID());
+        const tempHeaders = path.join(tempDir, randomUUID());
+        try {
+            await fs.writeFile(tempBlob, data);
+            await fs.writeFile(tempHeaders, JSON.stringify(headers), 'utf-8');
+            await this.linkIfAbsent(tempHeaders, this.headersSidecarPath(filePath));
+            return (await this.linkIfAbsent(tempBlob, filePath)) ? 'created' : 'already-exists';
+        }
+        finally {
+            await Promise.all([tempBlob, tempHeaders].map((temp) => fs.unlink(temp).catch(() => { })));
+        }
+    }
     async beginUpload(_input) {
         return {
             mode: 'proxied',
@@ -109,10 +151,11 @@ export class LocalAssetStore {
         await this.deleteFileIfPresent(this.resolveKey(key));
     }
     async putOriginal(input) {
-        const filePath = this.resolveKey(originalKey(input.hash32, input.ext));
-        await this.writeFile(filePath, input.data);
-        await this.writeHeadersSidecar(filePath, { contentType: input.contentType });
+        return this.createExclusive(originalKey(input.hash32, input.ext), input.data, {
+            contentType: input.contentType,
+        });
     }
+    /** Ignores the `ext` hint: a directory read costs nothing here and needs no permission. */
     async readOriginal(hash32) {
         const dir = this.resolveKey(ASSET_PREFIXES.originals);
         let entries;
@@ -125,7 +168,7 @@ export class LocalAssetStore {
             throw err;
         }
         const prefix = `${hash32}.`;
-        const match = entries.find((name) => name.startsWith(prefix) && !name.endsWith(HEADERS_SIDECAR_SUFFIX));
+        const match = entries.find((name) => name.startsWith(prefix) && ORIGINAL_EXT_RE.test(name.slice(prefix.length)));
         if (!match)
             return null;
         const filePath = path.join(dir, match);
@@ -136,14 +179,20 @@ export class LocalAssetStore {
         return { data, ext: match.slice(prefix.length), contentType: headers.contentType };
     }
     async putPublicObject(input) {
-        const filePath = this.resolveKey(input.key);
-        await this.writeFile(filePath, input.data);
-        await this.writeHeadersSidecar(filePath, {
+        return this.createExclusive(input.key, input.data, {
             contentType: input.contentType,
             contentDisposition: input.contentDisposition,
             cacheControl: input.cacheControl,
         });
     }
+    async copyPublicObject(sourceKey, destKey) {
+        const sourcePath = this.resolveKey(sourceKey);
+        const data = await this.readFileOrNull(sourcePath);
+        if (!data)
+            return 'source-missing';
+        const { contentType, contentDisposition, cacheControl } = await this.readHeadersSidecar(sourcePath);
+        return this.createExclusive(destKey, data, { contentType, contentDisposition, cacheControl });
+    }
     async readPublicObject(key) {
         const filePath = this.resolveKey(key);
         const data = await this.readFileOrNull(filePath);
@@ -157,6 +206,16 @@ export class LocalAssetStore {
             cacheControl: headers.cacheControl,
         };
     }
+    async hasPublicObject(key) {
+        try {
+            return (await fs.stat(this.resolveKey(key))).isFile();
+        }
+        catch (err) {
+            if (isNotFoundError(err))
+                return false;
+            throw err;
+        }
+    }
     /**
      * Atomic-exclusive create: opens with the `wx` flag so two concurrent
      * writers racing on the same hash32 have exactly one winner ('created')

package/dist/assets/store-s3.d.ts

@@ -1,11 +1,11 @@
 /**
  * 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 { type AssetPrefixes } from './keys.js';
-import type { AssetMeta, AssetStore, BeginUploadInput, PublicObject, StagedUploadTarget } from './types.js';
+import type { AssetMeta, AssetStore, BeginUploadInput, CreateOnlyResult, PublicObject, StagedUploadTarget } from './types.js';
 export interface S3AssetStoreOptions {
     bucket: string;
     region: string;
@@ -23,6 +23,8 @@ export interface S3AssetStoreOptions {
     uploadUrl?: string;
     /** Override the default bucket-prefix layout (rarely needed). */
     prefixes?: AssetPrefixes;
+    /** @internal Test seam for the conditional-write retry delay. */
+    sleep?: (ms: number) => Promise<void>;
 }
 export declare class S3AssetStore implements AssetStore {
     readonly capabilities: {
@@ -34,7 +36,19 @@ export declare class S3AssetStore implements AssetStore {
     private readonly uploadUrl;
     private readonly keys;
     private readonly stagingPrefix;
+    private readonly sleep;
     constructor(options: S3AssetStoreOptions);
+    /**
+     * 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.
+     */
+    private createIfAbsent;
+    private putIfAbsent;
     /**
      * Staging methods accept caller-influenced keys (finalize receives the key
      * from the client), so they must never operate outside the staging prefix —
@@ -59,8 +73,8 @@ export declare class S3AssetStore implements AssetStore {
         ext: string;
         data: Uint8Array;
         contentType: string;
-    }): Promise<void>;
-    readOriginal(hash32: string): Promise<{
+    }): Promise<CreateOnlyResult>;
+    readOriginal(hash32: string, ext?: string): Promise<{
         data: Uint8Array;
         ext: string;
         contentType?: string;
@@ -71,9 +85,26 @@ export declare class S3AssetStore implements AssetStore {
         contentType: string;
         contentDisposition?: string;
         cacheControl?: string;
-    }): Promise<void>;
+        tags?: Readonly<Record<string, string>>;
+    }): Promise<CreateOnlyResult>;
+    /**
+     * 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`.
+     */
+    copyPublicObject(sourceKey: string, destKey: string): Promise<CreateOnlyResult | 'source-missing'>;
     readPublicObject(key: string): Promise<PublicObject | null>;
-    putMetaIfAbsent(hash32: string, meta: AssetMeta): Promise<'created' | 'already-exists'>;
+    /**
+     * 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`.
+     */
+    hasPublicObject(key: string): Promise<boolean>;
+    listPublicObjectKeys(prefix: string): AsyncIterable<string>;
+    /** HEADs first: signing is local and succeeds for a missing key too. */
+    presignPublicObjectRead(key: string): Promise<string | null>;
+    putMetaIfAbsent(hash32: string, meta: AssetMeta): Promise<CreateOnlyResult>;
     getMeta(hash32: string): Promise<AssetMeta | null>;
     listMeta(input?: {
         cursor?: string;