canopycms 0.1.0 → 0.2.0-int.121

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, PresignedRead, PublicObject, StagedUploadTarget } from './types.js';
 export interface S3AssetStoreOptions {
     bucket: string;
     region: string;
@@ -102,18 +102,37 @@ export declare class S3AssetStore implements AssetStore {
      */
     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>;
+    private listKeys;
+    /**
+     * HEADs first: signing is local and succeeds for a missing key too. A URL signed with temporary
+     * credentials dies when they expire, whatever its own expiry, so `maxAgeSeconds` also stops short
+     * of the credentials' `expiration` when the provider reports one.
+     */
+    presignPublicObjectRead(key: string): Promise<PresignedRead | 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;
 }

package/dist/assets/store-s3.js

@@ -2,7 +2,7 @@
  * 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 { randomUUID } from 'node:crypto';
 import { CopyObjectCommand, DeleteObjectCommand, GetObjectCommand, HeadObjectCommand, ListObjectsV2Command, PutObjectCommand, S3Client, paginateListObjectsV2, } from '@aws-sdk/client-s3';
@@ -11,9 +11,18 @@ 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;
+/** What `metaKey` and `hiddenKey` put after the hash32. */
+const JSON_SUFFIX = '.json';
 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;
+/**
+ * A presigned read is signed at the start of its window, so every read of one key inside a window
+ * gets the same URL, and a browser can reuse both the redirect to it and the object behind it.
+ */
+const PRESIGNED_READ_WINDOW_SECONDS = 60 * 60;
+/** Valid a full window past the window's end, so a redirect cached until then never expires first. */
+const PRESIGNED_READ_EXPIRY_SECONDS = 2 * PRESIGNED_READ_WINDOW_SECONDS;
+/** How long before its signing credentials expire a presigned read stops being reusable. */
+const CREDENTIAL_EXPIRY_MARGIN_SECONDS = 60;
 function matchesAwsError(err, name, httpStatusCode) {
     if (!(err instanceof Error))
         return false;
@@ -234,7 +243,10 @@ export class S3AssetStore {
             throw err;
         }
     }
-    async *listPublicObjectKeys(prefix) {
+    listPublicObjectKeys(prefix) {
+        return this.listKeys(prefix);
+    }
+    async *listKeys(prefix) {
         const pages = paginateListObjectsV2({ client: this.client }, { Bucket: this.bucket, Prefix: prefix });
         for await (const page of pages) {
             for (const object of page.Contents ?? []) {
@@ -243,13 +255,25 @@ export class S3AssetStore {
             }
         }
     }
-    /** HEADs first: signing is local and succeeds for a missing key too. */
+    /**
+     * HEADs first: signing is local and succeeds for a missing key too. A URL signed with temporary
+     * credentials dies when they expire, whatever its own expiry, so `maxAgeSeconds` also stops short
+     * of the credentials' `expiration` when the provider reports one.
+     */
     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,
-        });
+        // Read before signing: a provider refresh in between leaves the signing credentials the newer.
+        const { expiration } = await this.client.config.credentials();
+        const nowSeconds = Math.floor(Date.now() / 1000);
+        const windowStart = nowSeconds - (nowSeconds % PRESIGNED_READ_WINDOW_SECONDS);
+        const url = await getSignedUrl(this.client, new GetObjectCommand({ Bucket: this.bucket, Key: key }), { expiresIn: PRESIGNED_READ_EXPIRY_SECONDS, signingDate: new Date(windowStart * 1000) });
+        let maxAgeSeconds = windowStart + PRESIGNED_READ_WINDOW_SECONDS - nowSeconds;
+        if (expiration) {
+            const credentialSeconds = Math.floor(expiration.getTime() / 1000) - nowSeconds;
+            maxAgeSeconds = Math.min(maxAgeSeconds, credentialSeconds - CREDENTIAL_EXPIRY_MARGIN_SECONDS);
+        }
+        return { url, maxAgeSeconds: Math.max(0, maxAgeSeconds) };
     }
     async putMetaIfAbsent(hash32, meta) {
         return this.putIfAbsent({
@@ -264,31 +288,69 @@ export class S3AssetStore {
             return null;
         return JSON.parse(Buffer.from(bytes).toString('utf-8'));
     }
+    /**
+     * 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`.
+     */
     async listMeta(input) {
-        const listed = await this.client.send(new ListObjectsV2Command({
-            Bucket: this.bucket,
-            Prefix: this.keys.metaPrefix(),
-            MaxKeys: input?.limit,
-            ContinuationToken: input?.cursor,
-        }));
+        const metaPrefix = this.keys.metaPrefix();
+        const [listed, hidden] = await Promise.all([
+            this.client.send(new ListObjectsV2Command({
+                Bucket: this.bucket,
+                Prefix: metaPrefix,
+                MaxKeys: input?.limit,
+                ContinuationToken: input?.cursor,
+            })),
+            this.listHiddenHashes(),
+        ]);
         const objectKeys = (listed.Contents ?? [])
             .map((obj) => obj.Key)
             .filter((key) => Boolean(key));
         const fetched = await Promise.all(objectKeys.map(async (key) => {
+            const isHidden = hidden.has(key.slice(metaPrefix.length, -JSON_SUFFIX.length));
+            if (isHidden && !input?.includeHidden)
+                return null;
             const bytes = await this.getObjectBytes(key);
-            // A meta object deleted between LIST and GET (deleteMeta race) reads
-            // as null; skip it rather than failing the whole page.
             if (!bytes)
                 return null;
-            return JSON.parse(Buffer.from(bytes).toString('utf-8'));
+            const meta = JSON.parse(Buffer.from(bytes).toString('utf-8'));
+            return isHidden ? { ...meta, hidden: true } : meta;
         }));
         return {
             items: fetched.filter((meta) => meta !== null),
             nextCursor: listed.IsTruncated ? listed.NextContinuationToken : undefined,
         };
     }
-    async deleteMeta(hash32) {
-        await this.client.send(new DeleteObjectCommand({ Bucket: this.bucket, Key: this.keys.metaKey(hash32) }));
+    async listHiddenHashes() {
+        const prefix = this.keys.hiddenPrefix();
+        const hashes = new Set();
+        for await (const key of this.listKeys(prefix)) {
+            if (key.endsWith(JSON_SUFFIX))
+                hashes.add(key.slice(prefix.length, -JSON_SUFFIX.length));
+        }
+        return hashes;
+    }
+    async hideAsset(hash32, marker) {
+        return this.putIfAbsent({
+            Key: this.keys.hiddenKey(hash32),
+            Body: JSON.stringify(marker),
+            ContentType: 'application/json',
+        });
+    }
+    /**
+     * 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.
+     */
+    async unhideAsset(hash32) {
+        const key = this.keys.hiddenKey(hash32);
+        const listed = await this.client.send(new ListObjectsV2Command({ Bucket: this.bucket, Prefix: key, MaxKeys: 1 }));
+        if (listed.Contents?.[0]?.Key !== key)
+            return false;
+        await this.client.send(new DeleteObjectCommand({ Bucket: this.bucket, Key: key }));
+        return true;
     }
     async getObject(key) {
         try {

package/dist/assets/types.d.ts

@@ -19,6 +19,15 @@ export interface AssetMeta {
     uploadedBy?: string;
     uploadedAt: string;
 }
+/** A listed asset; `hidden` is set only on a listing that includes hidden files. */
+export type ListedAssetMeta = AssetMeta & {
+    hidden?: true;
+};
+/** The body of a hidden marker. Only the marker's presence hides a file; this records who and when. */
+export interface HiddenAssetMarker {
+    hiddenAt: string;
+    hiddenBy?: string;
+}
 export type StagedUploadTarget = {
     mode: 'direct';
     url: string;
@@ -41,6 +50,11 @@ export interface PublicObject {
     contentDisposition?: string;
     cacheControl?: string;
 }
+/** A presigned GET, and how long a client may keep reusing that URL (0: not at all). */
+export interface PresignedRead {
+    url: string;
+    maxAgeSeconds: number;
+}
 /**
  * What a create-only write did. Every key the store writes this way is content-addressed, so no
  * correct writer ever replaces an object: `already-exists` means an object was already at the key
@@ -93,16 +107,31 @@ export interface AssetStore {
     hasPublicObject(key: string): Promise<boolean>;
     /** Every public object key under `prefix`, in the store's own pages. S3 only. */
     listPublicObjectKeys?(prefix: string): AsyncIterable<string>;
-    /** A short-lived URL a browser can GET `key` from directly, or `null` if absent. S3 only. */
-    presignPublicObjectRead?(key: string): Promise<string | null>;
+    /** A URL a browser can GET `key` from directly, or `null` if absent. S3 only. */
+    presignPublicObjectRead?(key: string): Promise<PresignedRead | null>;
+    /**
+     * Meta is create-only and never deleted: every transform not yet stored, at upload, release or
+     * after a lazy output expires, is computed from it, and content anywhere may still name the file.
+     */
     putMetaIfAbsent(hash32: string, meta: AssetMeta): Promise<CreateOnlyResult>;
     getMeta(hash32: string): Promise<AssetMeta | null>;
+    /**
+     * A page of meta, without hidden files unless `includeHidden`, which marks each hidden one
+     * `hidden: true`. A page may hold fewer than `limit` items while `nextCursor` is still set.
+     */
     listMeta(input?: {
         cursor?: string;
         limit?: number;
+        includeHidden?: boolean;
     }): Promise<{
-        items: AssetMeta[];
+        items: ListedAssetMeta[];
         nextCursor?: string;
     }>;
-    deleteMeta(hash32: string): Promise<void>;
+    /**
+     * Hide a file from `listMeta`: a create-only marker beside its meta, which stays, so every URL
+     * and transform keeps working. `already-exists` when it was hidden already.
+     */
+    hideAsset(hash32: string, marker: HiddenAssetMarker): Promise<CreateOnlyResult>;
+    /** Remove the hidden marker; `false` when there was none. Needs no permission on a store that has never hidden a file. */
+    unhideAsset(hash32: string): Promise<boolean>;
 }