canopycms 0.1.0 → 0.2.0-int.119

package/dist/api/assets.js

@@ -42,12 +42,14 @@ const finalizeAssetBodySchema = z.object({
 const listAssetsParamsSchema = z.object({
     cursor: z.string().optional(),
     limit: z.coerce.number().int().positive().max(100).optional(),
+    /** Admin only: also list files removed from the library, each marked `hidden: true`. */
+    includeHidden: z.enum(['true', 'false']).optional(),
 });
 /** hash32 is a sha-256 truncated to 32 hex chars (keys.ts's `hashBytes`) - never any other shape. */
 const hash32Schema = z
     .string()
     .regex(/^[a-f0-9]{32}$/, 'key must be a 32-character lowercase hex string');
-const deleteAssetParamsSchema = z.object({ key: hash32Schema });
+const assetKeyBodySchema = z.object({ key: hash32Schema });
 /**
  * Presign a direct (or proxied) upload target. Any authenticated user - there
  * is no finer "editor" role, and upload needs to work for every non-admin
@@ -75,7 +77,8 @@ const presignAssetHandler = async (ctx, _req, body) => {
 /**
  * Finalize a staged upload: read the staged bytes, run the finalize pipeline
  * (sniff/hash/dims/sanitize), write originals + meta, and return the result.
- * Any authenticated user (same rationale as presign).
+ * Any authenticated user (same rationale as presign). Uploading a file that was
+ * removed from the library puts it back; `finalizeAsset` says why.
  */
 const finalizeAssetHandler = async (ctx, req, body) => {
     if (!ctx.assetStore)
@@ -168,49 +171,82 @@ const uploadProxiedHandler = async (ctx, req) => {
 /**
  * List assets - any authenticated user can list assets (key enumeration is
  * accepted: unlisted != private, see .claude/future-tasks/resolved/assets-media-system.md).
+ * Files removed from the library are left out; only an admin may ask for them too.
  */
-const listAssetsHandler = async (ctx, _req, params) => {
+const listAssetsHandler = async (ctx, req, params) => {
     if (!ctx.assetStore)
         return { ok: false, status: 501, error: 'Asset store not configured' };
+    const includeHidden = params.includeHidden === 'true';
+    if (includeHidden && !isAdmin(req.user.groups)) {
+        return { ok: false, status: 403, error: 'Only admins can list removed files' };
+    }
     const { items, nextCursor } = await ctx.assetStore.listMeta({
         cursor: params.cursor,
         limit: params.limit,
+        includeHidden,
     });
     return { ok: true, status: 200, data: { assets: items.map(toAssetRecord), nextCursor } };
 };
 /**
- * Delete asset - an Admin may delete any asset; anyone else may delete only an asset whose
- * recorded `uploadedBy` is them. `key` (hash32) is pre-validated by `deleteAssetParamsSchema`.
- * Deletes the meta sidecar only - blobs are immortal until a future GC worker task (see
- * .claude/future-tasks/resolved/assets-media-system.md).
+ * Who may remove a file from the library or restore it: an admin may act on any file; anyone else
+ * only on a file whose recorded `uploadedBy` is them. `null` when the caller may act.
  *
- * The ownership check lives here, not in a declarative guard, because it needs the asset's meta,
- * which guards can't read. Two fail-closed choices:
+ * The check lives here, not in a declarative guard, because it needs the asset's meta, which
+ * guards can't read. Two fail-closed choices:
  * - Meta with no `uploadedBy` (the field is optional) is admin-only — defaulting to "anyone may
- *   delete" would open every legacy asset to everyone.
+ *   act" would open every legacy asset to everyone.
  * - A missing asset returns the same 403 as an unowned one for non-admins, so the endpoint isn't
- *   an existence oracle over a content-addressed keyspace.
+ *   an existence oracle over a content-addressed keyspace. An admin, who can list every file,
+ *   gets a 404, so no marker is ever written for a file that does not exist.
  *
  * `uploadedBy` records the FIRST uploader only: finalizeAsset dedups on content hash, so a second
- * person uploading an identical file gains no delete rights over it — benign (a 403 where they
- * expected success, never the reverse; see
- * safeinsights/canopycms#572).
+ * person uploading an identical file gains no rights over it — benign (a 403 where they expected
+ * success, never the reverse; see safeinsights/canopycms#572).
  *
  * Coupled to the blob-GC follow-up in safeinsights/canopycms#575: this permission is safe because
- * delete is a de-list, not a destroy — nothing another branch references breaks. If GC ever makes
- * delete destroy the blob, this needs a reference check too.
+ * removal hides a file and destroys nothing, so nothing any branch or build references breaks. If
+ * GC ever deletes blobs, it needs a reference check of its own.
+ */
+async function visibilityRefusal(store, req, key, verb) {
+    const meta = await store.getMeta(key);
+    if (isAdmin(req.user.groups)) {
+        return meta ? null : { ok: false, status: 404, error: 'File not found' };
+    }
+    if (!meta?.uploadedBy || meta.uploadedBy !== req.user.userId) {
+        return { ok: false, status: 403, error: `You can only ${verb} files you uploaded` };
+    }
+    return null;
+}
+/**
+ * Remove a file from the library: write its hidden marker and leave its meta, originals and
+ * public objects alone, so every URL and every transform, stored or not yet computed, keeps
+ * working for content on any branch and in any build. `visibilityRefusal` says who may.
+ *
+ * The marker is create-only, so a second remove finds it and changes nothing. Remove, restore
+ * and a re-upload's un-hide touch only the marker, and nothing but the library listing reads it:
+ * the worst interleaving of two of them lists or omits one file until the next action.
  */
-const deleteAssetHandler = async (ctx, req, params) => {
+const hideAssetHandler = async (ctx, req, body) => {
     if (!ctx.assetStore)
         return { ok: false, status: 501, error: 'Asset store not configured' };
-    if (!isAdmin(req.user.groups)) {
-        const meta = await ctx.assetStore.getMeta(params.key);
-        if (!meta?.uploadedBy || meta.uploadedBy !== req.user.userId) {
-            return { ok: false, status: 403, error: 'You can only delete assets you uploaded' };
-        }
-    }
-    await ctx.assetStore.deleteMeta(params.key);
-    return { ok: true, status: 200, data: { deleted: true } };
+    const refusal = await visibilityRefusal(ctx.assetStore, req, body.key, 'remove');
+    if (refusal)
+        return refusal;
+    await ctx.assetStore.hideAsset(body.key, {
+        hiddenAt: new Date().toISOString(),
+        hiddenBy: req.user.userId,
+    });
+    return { ok: true, status: 200, data: { hidden: true } };
+};
+/** Put a removed file back in the library by deleting its hidden marker; see `hideAssetHandler`. */
+const restoreAssetHandler = async (ctx, req, body) => {
+    if (!ctx.assetStore)
+        return { ok: false, status: 501, error: 'Asset store not configured' };
+    const refusal = await visibilityRefusal(ctx.assetStore, req, body.key, 'restore');
+    if (refusal)
+        return refusal;
+    await ctx.assetStore.unhideAsset(body.key);
+    return { ok: true, status: 200, data: { hidden: false } };
 };
 /**
  * The largest body this route returns inline. The CMS Lambda's Function URL buffers its response
@@ -382,20 +418,43 @@ const listAssets = defineEndpoint({
     defaultMockData: { assets: [] },
     handler: listAssetsHandler,
 });
-/**
- * DELETE /assets?key={hash32}
- */
-const deleteAsset = defineEndpoint({
+const hideAsset = defineEndpoint({
     namespace: 'assets',
-    name: 'delete',
-    method: 'DELETE',
-    path: '/assets',
-    params: deleteAssetParamsSchema,
-    responseType: 'AssetDeleteResponse',
+    name: 'hide',
+    method: 'POST',
+    path: '/assets/hide',
+    body: assetKeyBodySchema,
+    bodyType: 'AssetKeyBody',
+    responseType: 'AssetVisibilityResponse',
     response: {},
-    defaultMockData: { deleted: true },
-    handler: deleteAssetHandler,
+    defaultMockData: { hidden: true },
+    handler: hideAssetHandler,
 });
+const restoreAsset = defineEndpoint({
+    namespace: 'assets',
+    name: 'restore',
+    method: 'POST',
+    path: '/assets/restore',
+    body: assetKeyBodySchema,
+    bodyType: 'AssetKeyBody',
+    responseType: 'AssetVisibilityResponse',
+    response: {},
+    defaultMockData: { hidden: false },
+    handler: restoreAssetHandler,
+});
+/**
+ * DELETE /assets answers 410 instead of falling through to `DELETE /:branch` as a branch named
+ * "assets". Hand-built like `assetRawRoute`, so the client generator emits no method for it.
+ */
+const deleteAssetGone = {
+    method: 'DELETE',
+    pattern: ['assets'],
+    handler: async () => ({
+        ok: false,
+        status: 410,
+        error: 'DELETE /assets is gone: remove a file from the library with POST /assets/hide',
+    }),
+};
 /**
  * Exported routes for router registration and client codegen.
  */
@@ -404,7 +463,9 @@ export const ASSET_ROUTES = {
     finalize: finalizeAsset,
     uploadProxied,
     list: listAssets,
-    delete: deleteAsset,
+    hide: hideAsset,
+    restore: restoreAsset,
+    deleteGone: deleteAssetGone,
 };
 /**
  * GET /assets/raw/{key...} - see `rawAssetHandler` above for why this is

package/dist/api/client.d.ts

@@ -15,7 +15,7 @@ import type { ContentReadResponse, ContentWriteResponse, ReferenceValidationResp
 import type { ReferenceOptionsResponse } from './reference-options.js';
 import type { ResolveReferencesBody, ResolveReferencesResponse } from './resolve-references.js';
 import type { DeleteEntryResponse, EntriesResponse } from './entries.js';
-import type { AssetDeleteResponse, AssetsListResponse, FinalizeAssetBody, FinalizeAssetResponse, PresignAssetBody, PresignAssetResponse } from './assets.js';
+import type { AssetKeyBody, AssetVisibilityResponse, AssetsListResponse, FinalizeAssetBody, FinalizeAssetResponse, PresignAssetBody, PresignAssetResponse } from './assets.js';
 import type { BatchGetUserMetadataBody, BatchGetUserMetadataResponse, GetUserMetadataResponse, ListGroupsResponse, PermissionsResponse, SearchUsersResponse, UpdatePermissionsBody } from './permissions.js';
 import type { ExternalGroupsResponse, InternalGroupsResponse, UpdateInternalGroupsBody, UpdateInternalGroupsResponse } from './groups.js';
 import type { UserInfoResponse } from './user.js';
@@ -131,8 +131,10 @@ export declare class CanopyApiClient {
         } & RequestOptions) => Promise<FinalizeAssetResponse>;
         /** GET /assets */
         list: (params: Record<string, string>, options?: RequestOptions) => Promise<AssetsListResponse>;
-        /** DELETE /assets */
-        delete: (params: Record<string, string>, options?: RequestOptions) => Promise<AssetDeleteResponse>;
+        /** POST /assets/hide */
+        hide: (body: AssetKeyBody, options?: RequestOptions) => Promise<AssetVisibilityResponse>;
+        /** POST /assets/restore */
+        restore: (body: AssetKeyBody, options?: RequestOptions) => Promise<AssetVisibilityResponse>;
     };
     readonly permissions: {
         /** GET /permissions */

package/dist/api/client.js

@@ -139,9 +139,13 @@ export class CanopyApiClient {
             list: (params, options) => {
                 return this.request('GET', this.buildPath('/assets', params), undefined, 'standard', options);
             },
-            /** DELETE /assets */
-            delete: (params, options) => {
-                return this.request('DELETE', this.buildPath('/assets', params), undefined, 'standard', options);
+            /** POST /assets/hide */
+            hide: (body, options) => {
+                return this.request('POST', '/assets/hide', body, 'standard', options);
+            },
+            /** POST /assets/restore */
+            restore: (body, options) => {
+                return this.request('POST', '/assets/restore', body, 'standard', options);
             },
         };
         this.permissions = {

package/dist/api/index.d.ts

@@ -5,7 +5,7 @@ export type { CommentsResponse, AddCommentResponse, ResolveCommentResponse } fro
 export type { EntriesResponse, ListEntriesResponse, CollectionItem, ListEntriesParams, DeleteEntryResponse, } from './entries.js';
 export type { PermissionsResponse, UpdatePermissionsBody, SearchUsersParams, GetUserMetadataResponse, GetUserMetadataParams, } from './permissions.js';
 export type { UserInfoResponse } from './user.js';
-export type { AssetRecord, AssetsListResponse, PresignAssetResponse, PresignAssetBody, FinalizeAssetResponse, FinalizeAssetBody, AssetDeleteResponse, } from './assets.js';
+export type { AssetRecord, AssetsListResponse, PresignAssetResponse, PresignAssetBody, FinalizeAssetResponse, FinalizeAssetBody, AssetKeyBody, AssetVisibilityResponse, } from './assets.js';
 export type { InternalGroupsResponse, ExternalGroupsResponse, UpdateInternalGroupsBody, SearchExternalGroupsParams, ExternalGroup, } from './groups.js';
 export type { ReferenceOptionsResponse } from './reference-options.js';
 export type { ResolveReferencesResponse } from './resolve-references.js';

package/dist/assets/asset-prefixes.d.ts

@@ -1,5 +1,5 @@
 /**
- * The five S3/local bucket-prefix strings (see keys.ts's module doc for the full layout).
+ * The six S3/local bucket-prefix strings (see keys.ts's module doc for the full layout).
  *
  * Split into its own dependency-free file so isomorphic modules (transform-directives.ts,
  * asset-url.ts) can import the prefixes without pulling keys.ts's `node:crypto` import into a
@@ -9,6 +9,8 @@ export declare const ASSET_PREFIXES: {
     readonly originals: "asset-originals";
     readonly staging: "asset-staging";
     readonly meta: "asset-meta";
+    /** One marker per file removed from the media library; its meta stays (see `hideAsset`). */
+    readonly hidden: "asset-hidden";
     readonly public: "assets";
     /** Transform-output prefix; directive-aware key building lives in transform-directives.ts. */
     readonly transform: "assets/t";
@@ -21,6 +23,7 @@ export interface AssetPrefixes {
     originals: string;
     staging: string;
     meta: string;
+    hidden: string;
     public: string;
     transform: string;
 }

package/dist/assets/asset-prefixes.js

@@ -1,5 +1,5 @@
 /**
- * The five S3/local bucket-prefix strings (see keys.ts's module doc for the full layout).
+ * The six S3/local bucket-prefix strings (see keys.ts's module doc for the full layout).
  *
  * Split into its own dependency-free file so isomorphic modules (transform-directives.ts,
  * asset-url.ts) can import the prefixes without pulling keys.ts's `node:crypto` import into a
@@ -9,6 +9,8 @@ export const ASSET_PREFIXES = {
     originals: 'asset-originals',
     staging: 'asset-staging',
     meta: 'asset-meta',
+    /** One marker per file removed from the media library; its meta stays (see `hideAsset`). */
+    hidden: 'asset-hidden',
     public: 'assets',
     /** Transform-output prefix; directive-aware key building lives in transform-directives.ts. */
     transform: 'assets/t',

package/dist/assets/finalize.js

@@ -5,6 +5,8 @@
  */
 import { runFinalizePipeline } from './pipeline.js';
 import { ASSET_PREFIXES } from './keys.js';
+import { getErrorMessage } from '../utils/error.js';
+import { canopyLogWarn } from '../utils/logger.js';
 /**
  * A client-supplied staging key must be exactly `asset-staging/{uuid}` — the
  * shape beginUpload generates. Without this check, finalize's read + cleanup
@@ -37,8 +39,19 @@ export async function finalizeAsset(store, input) {
         return result;
     const { meta, data, publicObject } = result;
     const existing = await store.getMeta(meta.hash32);
-    if (existing)
+    if (existing) {
+        // Uploading a file removed from the library puts it back. Hiding is a de-list, not access
+        // control: whoever uploads the bytes has the file, and a picker selecting an upload the
+        // library never shows would be a dead end. A failed un-hide only leaves the file out of the
+        // listing, so the upload still succeeds.
+        try {
+            await store.unhideAsset(meta.hash32);
+        }
+        catch (err) {
+            canopyLogWarn(`[canopycms] could not restore removed asset ${meta.hash32} to the library on re-upload: ${getErrorMessage(err)}`);
+        }
         return { ok: true, meta: existing };
+    }
     // Either put may find its key taken (`already-exists`): by an earlier attempt that stopped
     // before the meta commit, or by a concurrent identical upload. The object kept there is this
     // content's, so finalize goes on to commit the meta either way.

package/dist/assets/keys.d.ts

@@ -7,6 +7,7 @@
  *   asset-originals/{hash32}.{ext}          private; full-fidelity originals
  *   asset-staging/{uuid}                    presigned-POST target
  *   asset-meta/{hash32}.json                private; filename/uploader/dims/mime
+ *   asset-hidden/{hash32}.json              private; marks a file removed from the library
  *   assets/t/{directives}/{hash32}/{slug}   transform outputs (see transform-directives.ts)
  *   assets/{hash32}/{slug}.{ext}            public static: sanitized SVG + PDF only
  *
@@ -50,8 +51,10 @@ export declare function createKeyBuilders(prefixes?: AssetPrefixes): {
     stagingKey: (uuid: string) => string;
     metaKey: (hash32: string) => string;
     metaPrefix: () => string;
+    hiddenKey: (hash32: string) => string;
+    hiddenPrefix: () => string;
     publicKey: (hash32: string, slug: string, ext: string) => string;
 };
-export declare const originalKey: (hash32: string, ext: string) => string, stagingKey: (uuid: string) => string, metaKey: (hash32: string) => string, publicKey: (hash32: string, slug: string, ext: string) => string;
+export declare const originalKey: (hash32: string, ext: string) => string, stagingKey: (uuid: string) => string, metaKey: (hash32: string) => string, hiddenKey: (hash32: string) => string, publicKey: (hash32: string, slug: string, ext: string) => string;
 /** @internal Exported for tests. */
 export declare const originalPrefix: (hash32: string) => string, metaPrefix: () => string;

package/dist/assets/keys.js

@@ -7,6 +7,7 @@
  *   asset-originals/{hash32}.{ext}          private; full-fidelity originals
  *   asset-staging/{uuid}                    presigned-POST target
  *   asset-meta/{hash32}.json                private; filename/uploader/dims/mime
+ *   asset-hidden/{hash32}.json              private; marks a file removed from the library
  *   assets/t/{directives}/{hash32}/{slug}   transform outputs (see transform-directives.ts)
  *   assets/{hash32}/{slug}.{ext}            public static: sanitized SVG + PDF only
  *
@@ -81,10 +82,12 @@ export function createKeyBuilders(prefixes = ASSET_PREFIXES) {
         stagingKey: (uuid) => `${prefixes.staging}/${uuid}`,
         metaKey: (hash32) => `${prefixes.meta}/${hash32}.json`,
         metaPrefix: () => `${prefixes.meta}/`,
+        hiddenKey: (hash32) => `${prefixes.hidden}/${hash32}.json`,
+        hiddenPrefix: () => `${prefixes.hidden}/`,
         publicKey: (hash32, slug, ext) => `${prefixes.public}/${hash32}/${slug}.${ext}`,
     };
 }
 const keyBuilders = createKeyBuilders();
-export const { originalKey, stagingKey, metaKey, publicKey } = keyBuilders;
+export const { originalKey, stagingKey, metaKey, hiddenKey, publicKey } = keyBuilders;
 /** @internal Exported for tests. */
 export const { originalPrefix, metaPrefix } = keyBuilders;

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

@@ -3,9 +3,9 @@
  * bucket-prefix layout as S3AssetStore (see keys.ts) so content behaves
  * identically across adapters.
  */
-import type { AssetMeta, AssetStore, BeginUploadInput, CreateOnlyResult, PublicObject, StagedUploadTarget } from './types.js';
+import type { AssetMeta, AssetStore, BeginUploadInput, CreateOnlyResult, HiddenAssetMarker, ListedAssetMeta, PublicObject, StagedUploadTarget } from './types.js';
 export interface LocalAssetStoreOptions {
-    /** Root directory. The five bucket prefixes are created as subdirectories under it. */
+    /** Root directory. The six bucket prefixes are created as subdirectories under it. */
     root: string;
 }
 export declare class LocalAssetStore implements AssetStore {
@@ -33,11 +33,12 @@ export declare class LocalAssetStore implements AssetStore {
     /** 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).
+     * Create-only write of a blob and, when `headers` is given, 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>;
@@ -85,12 +86,20 @@ export declare class LocalAssetStore implements AssetStore {
      */
     putMetaIfAbsent(hash32: string, meta: AssetMeta): Promise<CreateOnlyResult>;
     getMeta(hash32: string): Promise<AssetMeta | null>;
+    /**
+     * The cursor names the last item returned, and the next page starts after it in sort order, so a
+     * page boundary holds when that item is hidden in between: its meta is never deleted, and the
+     * comparison needs only its place, not its presence in the filtered list.
+     */
     listMeta(input?: {
         cursor?: string;
         limit?: number;
+        includeHidden?: boolean;
     }): Promise<{
-        items: AssetMeta[];
+        items: ListedAssetMeta[];
         nextCursor?: string;
     }>;
-    deleteMeta(hash32: string): Promise<void>;
+    private hiddenHashes;
+    hideAsset(hash32: string, marker: HiddenAssetMarker): Promise<CreateOnlyResult>;
+    unhideAsset(hash32: string): Promise<boolean>;
 }

package/dist/assets/store-local.js

@@ -8,7 +8,7 @@ import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { getErrorMessage, isFileExistsError, isNotFoundError } from '../utils/error.js';
 import { atomicWriteFile } from '../utils/atomic-write.js';
-import { ASSET_PREFIXES, metaKey, originalKey, stagingKey } from './keys.js';
+import { ASSET_PREFIXES, hiddenKey, metaKey, originalKey, stagingKey } from './keys.js';
 /** Matches S3AssetStore's default; local has no separate configuration knob for it. */
 const DEFAULT_MAX_UPLOAD_BYTES = 50 * 1024 * 1024;
 const DEFAULT_LIST_LIMIT = 24;
@@ -20,6 +20,16 @@ const HEADERS_SIDECAR_SUFFIX = '.headers.json';
 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]+$/;
+/** A hidden marker's file name; a stray file in the directory fails it. */
+const HIDDEN_MARKER_RE = /^([a-f0-9]{32})\.json$/;
+/** Newest first; hash32 breaks a tie of equal timestamps, so every page boundary is stable. */
+function compareNewestFirst(a, b) {
+    if (a.uploadedAt !== b.uploadedAt)
+        return a.uploadedAt < b.uploadedAt ? 1 : -1;
+    if (a.hash32 === b.hash32)
+        return 0;
+    return a.hash32 < b.hash32 ? 1 : -1;
+}
 export class LocalAssetStore {
     constructor(options) {
         this.capabilities = { directUpload: false };
@@ -95,11 +105,12 @@ export class LocalAssetStore {
         }
     }
     /**
-     * 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).
+     * Create-only write of a blob and, when `headers` is given, 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);
@@ -112,8 +123,10 @@ export class LocalAssetStore {
         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));
+            if (headers) {
+                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 {
@@ -249,6 +262,11 @@ export class LocalAssetStore {
             throw err;
         }
     }
+    /**
+     * The cursor names the last item returned, and the next page starts after it in sort order, so a
+     * page boundary holds when that item is hidden in between: its meta is never deleted, and the
+     * comparison needs only its place, not its presence in the filtered list.
+     */
     async listMeta(input) {
         const limit = input?.limit ?? DEFAULT_LIST_LIMIT;
         const dir = this.resolveKey(ASSET_PREFIXES.meta);
@@ -269,42 +287,56 @@ export class LocalAssetStore {
                 all.push(JSON.parse(raw));
             }
             catch (err) {
-                // A meta file racing with deleteMeta is expected under concurrency;
-                // anything else is a real problem worth surfacing via getErrorMessage.
+                // Only a file removed by hand since the directory read is skipped; anything else is a real
+                // problem worth surfacing via getErrorMessage.
                 if (!isNotFoundError(err)) {
                     throw new Error(`Failed to read asset meta file '${name}': ${getErrorMessage(err)}`);
                 }
             }
         }
-        // Newest first; hash32 is the deterministic tiebreak for equal timestamps
-        // (common in fast test loops using Date.now()), which keeps pagination
-        // stable and duplicate/gap-free across calls.
-        all.sort((a, b) => {
-            if (a.uploadedAt !== b.uploadedAt)
-                return a.uploadedAt < b.uploadedAt ? 1 : -1;
-            return a.hash32 < b.hash32 ? 1 : -1;
-        });
+        all.sort(compareNewestFirst);
+        const hidden = await this.hiddenHashes();
+        const listed = input?.includeHidden
+            ? all.map((meta) => (hidden.has(meta.hash32) ? { ...meta, hidden: true } : meta))
+            : all.filter((meta) => !hidden.has(meta.hash32));
         let startIndex = 0;
         if (input?.cursor) {
             const afterHash32 = Buffer.from(input.cursor, 'base64').toString('utf-8');
-            const idx = all.findIndex((m) => m.hash32 === afterHash32);
-            startIndex = idx === -1 ? 0 : idx + 1;
+            const anchor = all.find((m) => m.hash32 === afterHash32);
+            if (anchor) {
+                const after = listed.findIndex((m) => compareNewestFirst(m, anchor) > 0);
+                startIndex = after === -1 ? listed.length : after;
+            }
         }
-        const items = all.slice(startIndex, startIndex + limit);
-        const hasMore = startIndex + limit < all.length;
+        const items = listed.slice(startIndex, startIndex + limit);
+        const hasMore = startIndex + limit < listed.length;
         const nextCursor = hasMore
             ? Buffer.from(items[items.length - 1].hash32, 'utf-8').toString('base64')
             : undefined;
         return { items, nextCursor };
     }
-    async deleteMeta(hash32) {
-        const filePath = this.resolveKey(metaKey(hash32));
+    async hiddenHashes() {
         try {
-            await fs.unlink(filePath);
+            const names = await fs.readdir(this.resolveKey(ASSET_PREFIXES.hidden));
+            return new Set(names.flatMap((name) => HIDDEN_MARKER_RE.exec(name)?.[1] ?? []));
+        }
+        catch (err) {
+            if (isNotFoundError(err))
+                return new Set();
+            throw err;
+        }
+    }
+    async hideAsset(hash32, marker) {
+        return this.createExclusive(hiddenKey(hash32), new TextEncoder().encode(JSON.stringify(marker)));
+    }
+    async unhideAsset(hash32) {
+        try {
+            await fs.unlink(this.resolveKey(hiddenKey(hash32)));
+            return true;
         }
         catch (err) {
             if (isNotFoundError(err))
-                return;
+                return false;
             throw err;
         }
     }

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

@@ -2,10 +2,10 @@
  * 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). It reads and writes under the
- * five asset prefixes, plus a caller's output prefix for `copyPublicObject`.
+ * six asset prefixes, plus a caller's output prefix for `copyPublicObject`.
  */
 import { type AssetPrefixes } from './keys.js';
-import type { AssetMeta, AssetStore, BeginUploadInput, CreateOnlyResult, PublicObject, StagedUploadTarget } from './types.js';
+import type { AssetMeta, AssetStore, BeginUploadInput, CreateOnlyResult, HiddenAssetMarker, ListedAssetMeta, PublicObject, StagedUploadTarget } from './types.js';
 export interface S3AssetStoreOptions {
     bucket: string;
     region: string;
@@ -102,18 +102,33 @@ export declare class S3AssetStore implements AssetStore {
      */
     hasPublicObject(key: string): Promise<boolean>;
     listPublicObjectKeys(prefix: string): AsyncIterable<string>;
+    private listKeys;
     /** 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>;
+    /**
+     * One page of meta keys, filtered by a full listing of the hidden markers: few files are hidden,
+     * and a listing needs only `s3:ListBucket`. A hidden file's meta is fetched only for
+     * `includeHidden`.
+     */
     listMeta(input?: {
         cursor?: string;
         limit?: number;
+        includeHidden?: boolean;
     }): Promise<{
-        items: AssetMeta[];
+        items: ListedAssetMeta[];
         nextCursor?: string;
     }>;
-    deleteMeta(hash32: string): Promise<void>;
+    private listHiddenHashes;
+    hideAsset(hash32: string, marker: HiddenAssetMarker): Promise<CreateOnlyResult>;
+    /**
+     * Lists before deleting: a DELETE of an absent key writes a delete marker on a versioned bucket.
+     * The listing needs only `s3:ListBucket` covering `asset-hidden/` (a bucket-wide grant does; a
+     * policy scoping it by prefix must name this one), no object permission, so finalize can call
+     * this on every re-upload under a role that has never hidden a file.
+     */
+    unhideAsset(hash32: string): Promise<boolean>;
     private getObject;
     private getObjectBytes;
 }