@hollware/core 1.0.0-rc.0 → 1.0.0-rc.2

package/dist/index.d.mts

@@ -1,3 +1,4 @@
+import { EVENT_ID_HEADER, SIGNATURE_HEADER, TIMESTAMP_HEADER, WebhookCheck, signWebhook, verifyWebhook } from "./webhooks.mjs";
 import * as z from "zod";
 import "@cfworker/json-schema";
 import { MarkdownDocument } from "comark";
@@ -327,6 +328,12 @@ interface SiteDefinition {
     /** How many days a line is kept, 30 to 3650; `null` keeps the log as long as the site. */
     readonly retentionDays?: number | null;
   };
+  /** How the site converts the images it receives (ADR-038): WebP at 85, 2400 pixels wide. */
+  readonly media?: {
+    readonly format?: 'webp' | 'avif' | 'original';
+    readonly quality?: number;
+    readonly maxWidth?: number;
+  };
 }
 /** What `hollware.config.ts` exports. */
 interface HollwareConfig {
@@ -377,6 +384,16 @@ interface ResolvedSite {
   };
   readonly events: ResolvedEvents;
   readonly audit: ResolvedAudit;
+  readonly media: ResolvedMedia;
+}
+/** How a site converts the images it receives (ADR-038). */
+interface ResolvedMedia {
+  /** `original` keeps every file as it came; the others convert JPEG, PNG and GIF. */
+  readonly format: 'webp' | 'avif' | 'original';
+  /** The quality of photographs, 1 to 100; PNG is converted lossless whatever it says. */
+  readonly quality: number;
+  /** The widest an image is kept, in pixels; a wider one is scaled down, never up. */
+  readonly maxWidth: number;
 }
 /** What the activity log of a site keeps (ADR-037). */
 interface ResolvedAudit {
@@ -471,6 +488,16 @@ export declare const AUDIT_RETENTION_MAX_DAYS = 3650;
 /** What a site that says nothing keeps: no addresses, and the log for as long as the site exists. */
 export declare const DEFAULT_AUDIT: ResolvedAudit;
 //#endregion
+//#region src/config/media.d.ts
+/** The formats a site may convert its images to, or keep them as they came (ADR-038). */
+export declare const MEDIA_FORMATS: readonly ['webp', 'avif', 'original'];
+/** The narrowest an image may be scaled down to: smaller would blur on every screen. */
+export declare const MEDIA_MIN_WIDTH = 320;
+/** The widest: past it the binding's area limit comes first, and no page shows more. */
+export declare const MEDIA_MAX_WIDTH = 8192;
+/** What a site that says nothing gets: WebP at 85, and nothing wider than 2400 pixels. */
+export declare const DEFAULT_MEDIA: ResolvedMedia;
+//#endregion
 //#region src/config/constants.d.ts
 /** The largest Markdown file a collection accepts when its config does not say, 512 KiB. */
 export declare const DEFAULT_MAX_MARKDOWN_BYTES = 524288;
@@ -1151,7 +1178,7 @@ export declare function isSiteKey(value: unknown): value is string;
  * operation or route that changes something is not logged until it is named here.
  */
 /** Every operation that is not a read: each call of one is a line, whatever its outcome. */
-export declare const OPERATION_AUDIT_ACTIONS: readonly ['create_draft', 'update_draft', 'publish', 'unpublish', 'delete_entry', 'restore_entry', 'approve_review', 'request_review', 'comment_review', 'request_changes', 'update_site', 'set_collection', 'create_site', 'delete_site', 'restore_site', 'make_webhook_secret'];
+export declare const OPERATION_AUDIT_ACTIONS: readonly ['create_draft', 'update_draft', 'publish', 'unpublish', 'delete_entry', 'restore_entry', 'approve_review', 'request_review', 'comment_review', 'request_changes', 'update_site', 'set_collection', 'create_site', 'delete_site', 'restore_site', 'make_webhook_secret', 'upload_asset'];
 /** What people do outside the operations: their tokens, members, passkeys, sessions and apps. */
 export declare const IDENTITY_AUDIT_ACTIONS: readonly ['token.create',
 /** A person asked for a link that shows an entry's latest revision on the site (T-103). */
@@ -1160,7 +1187,7 @@ export declare const IDENTITY_AUDIT_ACTIONS: readonly ['token.create',
 'app.refresh_reused',
 /** The cron published an entry whose time had come, for the person who scheduled it. */
 'schedule.publish'];
-export declare const AUDIT_ACTIONS: readonly ["create_draft", "update_draft", "publish", "unpublish", "delete_entry", "restore_entry", "approve_review", "request_review", "comment_review", "request_changes", "update_site", "set_collection", "create_site", "delete_site", "restore_site", "make_webhook_secret", "token.create", "preview.create", "token.revoke", "member.role", "member.remove", "invitation.create", "invitation.accept", "session.sign_in", "session.sign_out", "session.end_all", "passkey.remove", "app.allow", "app.revoke", "app.refresh_reused", "schedule.publish"];
+export declare const AUDIT_ACTIONS: readonly ["create_draft", "update_draft", "publish", "unpublish", "delete_entry", "restore_entry", "approve_review", "request_review", "comment_review", "request_changes", "update_site", "set_collection", "create_site", "delete_site", "restore_site", "make_webhook_secret", "upload_asset", "token.create", "preview.create", "token.revoke", "member.role", "member.remove", "invitation.create", "invitation.accept", "session.sign_in", "session.sign_out", "session.end_all", "passkey.remove", "app.allow", "app.revoke", "app.refresh_reused", "schedule.publish"];
 export type AuditAction = (typeof AUDIT_ACTIONS)[number];
 /** `denied`: a scope or a role was missing; `failed`: any other error the caller got. */
 export declare const AUDIT_OUTCOMES: readonly ['ok', 'denied', 'failed'];
@@ -1245,6 +1272,15 @@ export declare const siteDefinitionData: z.ZodObject<{
     }>>;
     retentionDays: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
   }, z.core.$strict>>;
+  media: z.ZodDefault<z.ZodObject<{
+    format: z.ZodDefault<z.ZodEnum<{
+      avif: "avif";
+      original: "original";
+      webp: "webp";
+    }>>;
+    quality: z.ZodDefault<z.ZodNumber>;
+    maxWidth: z.ZodDefault<z.ZodNumber>;
+  }, z.core.$strict>>;
   collections: z.ZodRecord<z.ZodString, z.ZodObject<{
     schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     routes: z.ZodRecord<z.ZodString, z.ZodString>;
@@ -1351,6 +1387,7 @@ export declare class HollwareError extends Error {
  */
 /** The kinds of ids and their prefixes. A new kind adds its prefix here. */
 export declare const ID_PREFIXES: {
+  readonly asset: 'ast';
   readonly auditLine: 'aud';
   readonly challenge: 'chl';
   readonly delivery: 'dlv';
@@ -2420,6 +2457,123 @@ export declare const contentStats: OperationSpec<"content_stats", z.ZodObject<{
     }, z.core.$strip>>;
   }, z.core.$strip>>>;
 }, z.core.$strip>>;
+export declare const uploadAsset: OperationSpec<"upload_asset", z.ZodObject<{
+  filename: z.ZodString;
+  alt: z.ZodString;
+  data: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+  outcome: z.ZodEnum<{
+    created: "created";
+    exists: "exists";
+    refused: "refused";
+    unavailable: "unavailable";
+  }>;
+  asset: z.ZodOptional<z.ZodObject<{
+    id: z.ZodString;
+    reference: z.ZodString;
+    url: z.ZodString;
+    format: z.ZodEnum<{
+      "image/avif": "image/avif";
+      "image/gif": "image/gif";
+      "image/jpeg": "image/jpeg";
+      "image/png": "image/png";
+      "image/svg+xml": "image/svg+xml";
+      "image/webp": "image/webp";
+    }>;
+    width: z.ZodNullable<z.ZodNumber>;
+    height: z.ZodNullable<z.ZodNumber>;
+    bytes: z.ZodNumber;
+    originalFormat: z.ZodEnum<{
+      "image/avif": "image/avif";
+      "image/gif": "image/gif";
+      "image/jpeg": "image/jpeg";
+      "image/png": "image/png";
+      "image/svg+xml": "image/svg+xml";
+      "image/webp": "image/webp";
+    }>;
+    originalBytes: z.ZodNumber;
+    alt: z.ZodString;
+    filename: z.ZodString;
+    createdAt: z.ZodString;
+  }, z.core.$strip>>;
+  problem: z.ZodOptional<z.ZodObject<{
+    message: z.ZodString;
+    fix: z.ZodString;
+  }, z.core.$strip>>;
+}, z.core.$strip>>;
+export declare const listAssets: OperationSpec<"list_assets", z.ZodObject<{
+  limit: z.ZodDefault<z.ZodNumber>;
+  cursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+  outcome: z.ZodEnum<{
+    ok: "ok";
+  }>;
+  assets: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    reference: z.ZodString;
+    url: z.ZodString;
+    format: z.ZodEnum<{
+      "image/avif": "image/avif";
+      "image/gif": "image/gif";
+      "image/jpeg": "image/jpeg";
+      "image/png": "image/png";
+      "image/svg+xml": "image/svg+xml";
+      "image/webp": "image/webp";
+    }>;
+    width: z.ZodNullable<z.ZodNumber>;
+    height: z.ZodNullable<z.ZodNumber>;
+    bytes: z.ZodNumber;
+    originalFormat: z.ZodEnum<{
+      "image/avif": "image/avif";
+      "image/gif": "image/gif";
+      "image/jpeg": "image/jpeg";
+      "image/png": "image/png";
+      "image/svg+xml": "image/svg+xml";
+      "image/webp": "image/webp";
+    }>;
+    originalBytes: z.ZodNumber;
+    alt: z.ZodString;
+    filename: z.ZodString;
+    createdAt: z.ZodString;
+  }, z.core.$strip>>;
+  nextCursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>>;
+export declare const getAsset: OperationSpec<"get_asset", z.ZodObject<{
+  id: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+  outcome: z.ZodEnum<{
+    not_found: "not_found";
+    ok: "ok";
+  }>;
+  asset: z.ZodOptional<z.ZodObject<{
+    id: z.ZodString;
+    reference: z.ZodString;
+    url: z.ZodString;
+    format: z.ZodEnum<{
+      "image/avif": "image/avif";
+      "image/gif": "image/gif";
+      "image/jpeg": "image/jpeg";
+      "image/png": "image/png";
+      "image/svg+xml": "image/svg+xml";
+      "image/webp": "image/webp";
+    }>;
+    width: z.ZodNullable<z.ZodNumber>;
+    height: z.ZodNullable<z.ZodNumber>;
+    bytes: z.ZodNumber;
+    originalFormat: z.ZodEnum<{
+      "image/avif": "image/avif";
+      "image/gif": "image/gif";
+      "image/jpeg": "image/jpeg";
+      "image/png": "image/png";
+      "image/svg+xml": "image/svg+xml";
+      "image/webp": "image/webp";
+    }>;
+    originalBytes: z.ZodNumber;
+    alt: z.ZodString;
+    filename: z.ZodString;
+    createdAt: z.ZodString;
+  }, z.core.$strip>>;
+}, z.core.$strip>>;
 /** Every operation, sorted by name: the order of `tools/list`. */
 export declare const OPERATIONS: readonly [OperationSpec<"approve_review", z.ZodObject<{
   id: z.ZodString;
@@ -2640,6 +2794,15 @@ export declare const OPERATIONS: readonly [OperationSpec<"approve_review", z.Zod
       }>>;
       retentionDays: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
     }, z.core.$strict>>;
+    media: z.ZodDefault<z.ZodObject<{
+      format: z.ZodDefault<z.ZodEnum<{
+        avif: "avif";
+        original: "original";
+        webp: "webp";
+      }>>;
+      quality: z.ZodDefault<z.ZodNumber>;
+      maxWidth: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
     collections: z.ZodRecord<z.ZodString, z.ZodObject<{
       schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
       routes: z.ZodRecord<z.ZodString, z.ZodString>;
@@ -2759,6 +2922,41 @@ export declare const OPERATIONS: readonly [OperationSpec<"approve_review", z.Zod
       styleGuide: z.ZodNullable<z.ZodString>;
     }, z.core.$strip>>;
   }, z.core.$strip>;
+}, z.core.$strip>>, OperationSpec<"get_asset", z.ZodObject<{
+  id: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+  outcome: z.ZodEnum<{
+    not_found: "not_found";
+    ok: "ok";
+  }>;
+  asset: z.ZodOptional<z.ZodObject<{
+    id: z.ZodString;
+    reference: z.ZodString;
+    url: z.ZodString;
+    format: z.ZodEnum<{
+      "image/avif": "image/avif";
+      "image/gif": "image/gif";
+      "image/jpeg": "image/jpeg";
+      "image/png": "image/png";
+      "image/svg+xml": "image/svg+xml";
+      "image/webp": "image/webp";
+    }>;
+    width: z.ZodNullable<z.ZodNumber>;
+    height: z.ZodNullable<z.ZodNumber>;
+    bytes: z.ZodNumber;
+    originalFormat: z.ZodEnum<{
+      "image/avif": "image/avif";
+      "image/gif": "image/gif";
+      "image/jpeg": "image/jpeg";
+      "image/png": "image/png";
+      "image/svg+xml": "image/svg+xml";
+      "image/webp": "image/webp";
+    }>;
+    originalBytes: z.ZodNumber;
+    alt: z.ZodString;
+    filename: z.ZodString;
+    createdAt: z.ZodString;
+  }, z.core.$strip>>;
 }, z.core.$strip>>, OperationSpec<"get_entry", z.ZodObject<{
   collection: z.ZodString;
   locale: z.ZodString;
@@ -2922,6 +3120,15 @@ export declare const OPERATIONS: readonly [OperationSpec<"approve_review", z.Zod
       }>>;
       retentionDays: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
     }, z.core.$strict>>;
+    media: z.ZodDefault<z.ZodObject<{
+      format: z.ZodDefault<z.ZodEnum<{
+        avif: "avif";
+        original: "original";
+        webp: "webp";
+      }>>;
+      quality: z.ZodDefault<z.ZodNumber>;
+      maxWidth: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
     collections: z.ZodRecord<z.ZodString, z.ZodObject<{
       schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
       routes: z.ZodRecord<z.ZodString, z.ZodString>;
@@ -2979,6 +3186,42 @@ export declare const OPERATIONS: readonly [OperationSpec<"approve_review", z.Zod
     deletedAt: z.ZodNullable<z.ZodString>;
     updatedAt: z.ZodString;
   }, z.core.$strip>>>;
+}, z.core.$strip>>, OperationSpec<"list_assets", z.ZodObject<{
+  limit: z.ZodDefault<z.ZodNumber>;
+  cursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+  outcome: z.ZodEnum<{
+    ok: "ok";
+  }>;
+  assets: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    reference: z.ZodString;
+    url: z.ZodString;
+    format: z.ZodEnum<{
+      "image/avif": "image/avif";
+      "image/gif": "image/gif";
+      "image/jpeg": "image/jpeg";
+      "image/png": "image/png";
+      "image/svg+xml": "image/svg+xml";
+      "image/webp": "image/webp";
+    }>;
+    width: z.ZodNullable<z.ZodNumber>;
+    height: z.ZodNullable<z.ZodNumber>;
+    bytes: z.ZodNumber;
+    originalFormat: z.ZodEnum<{
+      "image/avif": "image/avif";
+      "image/gif": "image/gif";
+      "image/jpeg": "image/jpeg";
+      "image/png": "image/png";
+      "image/svg+xml": "image/svg+xml";
+      "image/webp": "image/webp";
+    }>;
+    originalBytes: z.ZodNumber;
+    alt: z.ZodString;
+    filename: z.ZodString;
+    createdAt: z.ZodString;
+  }, z.core.$strip>>;
+  nextCursor: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>>, OperationSpec<"list_entries", z.ZodObject<{
   collection: z.ZodString;
   locale: z.ZodOptional<z.ZodString>;
@@ -3423,6 +3666,8 @@ export declare const OPERATIONS: readonly [OperationSpec<"approve_review", z.Zod
     }, z.core.$strip>>;
   }, z.core.$strip>>;
   currentVersion: z.ZodOptional<z.ZodNumber>;
+  message: z.ZodOptional<z.ZodString>;
+  fix: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>>, OperationSpec<"unpublish", z.ZodObject<{
   id: z.ZodString;
 }, z.core.$strict>, z.ZodObject<{
@@ -3543,6 +3788,15 @@ export declare const OPERATIONS: readonly [OperationSpec<"approve_review", z.Zod
       }>>;
       retentionDays: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
     }, z.core.$strict>>;
+    media: z.ZodDefault<z.ZodObject<{
+      format: z.ZodDefault<z.ZodEnum<{
+        avif: "avif";
+        original: "original";
+        webp: "webp";
+      }>>;
+      quality: z.ZodDefault<z.ZodNumber>;
+      maxWidth: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
     collections: z.ZodRecord<z.ZodString, z.ZodObject<{
       schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
       routes: z.ZodRecord<z.ZodString, z.ZodString>;
@@ -3598,6 +3852,51 @@ export declare const OPERATIONS: readonly [OperationSpec<"approve_review", z.Zod
     }, z.core.$strip>>;
   }, z.core.$strip>>;
   currentVersion: z.ZodOptional<z.ZodNumber>;
+  message: z.ZodOptional<z.ZodString>;
+  fix: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>, OperationSpec<"upload_asset", z.ZodObject<{
+  filename: z.ZodString;
+  alt: z.ZodString;
+  data: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+  outcome: z.ZodEnum<{
+    created: "created";
+    exists: "exists";
+    refused: "refused";
+    unavailable: "unavailable";
+  }>;
+  asset: z.ZodOptional<z.ZodObject<{
+    id: z.ZodString;
+    reference: z.ZodString;
+    url: z.ZodString;
+    format: z.ZodEnum<{
+      "image/avif": "image/avif";
+      "image/gif": "image/gif";
+      "image/jpeg": "image/jpeg";
+      "image/png": "image/png";
+      "image/svg+xml": "image/svg+xml";
+      "image/webp": "image/webp";
+    }>;
+    width: z.ZodNullable<z.ZodNumber>;
+    height: z.ZodNullable<z.ZodNumber>;
+    bytes: z.ZodNumber;
+    originalFormat: z.ZodEnum<{
+      "image/avif": "image/avif";
+      "image/gif": "image/gif";
+      "image/jpeg": "image/jpeg";
+      "image/png": "image/png";
+      "image/svg+xml": "image/svg+xml";
+      "image/webp": "image/webp";
+    }>;
+    originalBytes: z.ZodNumber;
+    alt: z.ZodString;
+    filename: z.ZodString;
+    createdAt: z.ZodString;
+  }, z.core.$strip>>;
+  problem: z.ZodOptional<z.ZodObject<{
+    message: z.ZodString;
+    fix: z.ZodString;
+  }, z.core.$strip>>;
 }, z.core.$strip>>, OperationSpec<"validate", z.ZodObject<{
   collection: z.ZodString;
   locale: z.ZodString;
@@ -3675,41 +3974,56 @@ export declare function isReadToken(value: string): boolean;
 /** The SHA-256 of a token, in lowercase hex: what the `tokens` table stores and looks up. */
 export declare function hashPersonalToken(token: string): Promise<string>;
 //#endregion
-//#region src/webhooks.d.ts
-/**
- * The signature of Hollware's webhooks (ADR-025), for the Worker that sends them and for whoever
- * receives them: HMAC-SHA256 of `<timestamp>.<body>` with the webhook's secret, sent as
- * `hollware-signature: v1=<hex>` with `hollware-timestamp` (seconds since the epoch) and
- * `hollware-event-id`. Web Crypto only, so it runs in any runtime.
- */
-export declare const SIGNATURE_HEADER = "hollware-signature";
-export declare const TIMESTAMP_HEADER = "hollware-timestamp";
-export declare const EVENT_ID_HEADER = "hollware-event-id";
-/** The value of `hollware-signature` for a body sent at `timestamp` (seconds). */
-export declare function signWebhook(secret: string, timestamp: number, body: string): Promise<string>;
-export interface WebhookCheck {
-  readonly secret: string;
-  /** The raw body, as received: a parsed and re-serialized body no longer matches. */
-  readonly body: string;
-  readonly headers: Headers;
-  /** Now, in seconds since the epoch; the system clock when absent. */
-  readonly now?: number;
-  readonly toleranceSeconds?: number;
+//#region src/media/index.d.ts
+/** The kinds of image Hollware takes, by media type. */
+export declare const IMAGE_FORMATS: readonly ['image/jpeg', 'image/png', 'image/webp', 'image/avif', 'image/gif', 'image/svg+xml'];
+export type ImageFormat = (typeof IMAGE_FORMATS)[number];
+/** The largest file `upload_asset` takes, in bytes: the binding takes 20 MB, this keeps room. */
+export declare const MAX_ASSET_BYTES: number;
+/** The extension a format is served and exported with. */
+export declare const EXTENSIONS: Readonly<Record<ImageFormat, string>>;
+/**
+ * The format of a file, read from its bytes and never from its name or a header: `null` for
+ * anything else. An SVG is text that opens on `<svg` or on an XML declaration followed by one.
+ */
+export declare function sniffImage(bytes: Uint8Array): ImageFormat | null;
+/** Why an SVG is refused, and what to do: an SVG is taken only when nothing in it can run. */
+export interface SvgProblem {
+  readonly reason: string;
+  readonly fix: string;
+}
+/** `null` when an SVG holds nothing that can run or reach out, else the first thing that can. */
+export declare function checkSvg(source: string): SvgProblem | null;
+/** What the binding is asked for, or `null` to keep the file as it came. */
+export interface Conversion {
+  readonly format: 'image/webp' | 'image/avif';
   /**
-   * Whether the receiver sees this event for the first time, given its id, and records it (T-67):
-   * a request captured and sent again within the tolerance is then refused. The id is read from
-   * the signed body, never from `hollware-event-id`, which no signature covers. A retry of a
-   * delivery carries the same id, so a receiver that records an id only once it has handled the
-   * event lets a failed delivery be retried. Keep each id for longer than the tolerance.
+   * Always given: the binding's default is lossless, not 85 (ADR-038). 100 for PNG, which holds
+   * screenshots, diagrams and logos: lossless keeps their edges.
    */
-  readonly isNew?: (eventId: string) => boolean | Promise<boolean>;
+  readonly quality: number;
+  /** Always given: without it the binding keeps one frame of an animation. */
+  readonly anim: boolean;
+  /** The width to scale down to, when the image is wider than the site allows. */
+  readonly width?: number;
 }
 /**
- * Whether a request is a webhook of Hollware: its signature matches the body and the secret, and
- * its timestamp is within the tolerance, so a captured request cannot be replayed later; with
- * `isNew`, also that its event was not received before, so it cannot be replayed sooner either.
+ * What a file of `format`, `width` pixels wide (null for an SVG), becomes under `media`: JPEG,
+ * PNG and GIF become the site's format; a WebP or an AVIF keeps its own and is only scaled down
+ * when it is wider than the site allows; `original` and SVG keep every file as it came.
+ */
+export declare function conversionOf(format: ImageFormat, width: number | null, media: ResolvedMedia): Conversion | null;
+/** The id of an asset, from the SHA-256 of its original bytes: the same file is the same asset. */
+export declare function assetIdOf(sha256Hex: string): string;
+/** What content writes to name an asset: `asset:ast_…`. */
+export declare const ASSET_SCHEME = "asset:";
+/** The id an `asset:` reference names, or `null` when the value is no such reference. */
+export declare function assetIdIn(value: string): string | null;
+/**
+ * A copy of a value (a frontmatter, a document) with every string that is an `asset:` reference
+ * replaced by the URL `urlOf` gives its id. Everything else is copied as it is.
  */
-export declare function verifyWebhook(check: WebhookCheck): Promise<boolean>;
+export declare function resolveAssetReferences<T>(value: T, urlOf: (id: string) => string): T;
 //#endregion
 //#region src/preview.d.ts
 /**
@@ -3905,4 +4219,4 @@ export declare function tagsOfSiteChange(collections: readonly string[], locales
 //#region src/index.d.ts
 export declare const name = "@hollware/core";
 //#endregion
-export { type AcknowledgedWarning, type AuthDefinition, type BuiltInContractId, type BuiltInOptions, type CatalogRule, type Chunk, type CollectionDefinition, type CollectionDefinitionData, type ComponentDefinition, type ComponentUse, type ConfigProblem, type Contract, type ContractContext, type ContractDescription, type ContractFinding, type ContractText, type CustomContractOptions, type DescribedSchema, type DisallowedMarker, type Effect, type EntryDocument, type EntryEvent, type EntryFacts, type EntryLookup, type EntryRef, type ErrorCode, type ExtractedContent, type Heading, type HollwareConfig, type HollwareEvent, type IdPrefix, type ImageRef, type LinkRef, type LinkTarget, type Operation, type OperationByName, type OperationName, type OperationSpec, type OutcomeInfo, type OutcomeOf, type Phase, type Preset, type PreviewCheck, type PreviewRefusal, type ProcessMarkdown, type ProcessMarkdownOptions, type ProcessResult, type ProcessedMarkdown, type RenderHtml, type ResolveConfig, type ResolvedAudit, type ResolvedAuth, type ResolvedCollection, type ResolvedConfig, type ResolvedSite, type RuleDefinition, type RunContractsInput, type SchemaOutput, type Scope, type Severity, type SiteDefinition, type SiteDefinitionData, type SiteDefinitionInput, type SiteDescription, type SiteEvent, type TaggedEntry, type Verdict, type Violation, schemas_d_exports as schemas };
+export { type AcknowledgedWarning, type AuthDefinition, type BuiltInContractId, type BuiltInOptions, type CatalogRule, type Chunk, type CollectionDefinition, type CollectionDefinitionData, type ComponentDefinition, type ComponentUse, type ConfigProblem, type Contract, type ContractContext, type ContractDescription, type ContractFinding, type ContractText, type CustomContractOptions, type DescribedSchema, type DisallowedMarker, EVENT_ID_HEADER, type Effect, type EntryDocument, type EntryEvent, type EntryFacts, type EntryLookup, type EntryRef, type ErrorCode, type ExtractedContent, type Heading, type HollwareConfig, type HollwareEvent, type IdPrefix, type ImageRef, type LinkRef, type LinkTarget, type Operation, type OperationByName, type OperationName, type OperationSpec, type OutcomeInfo, type OutcomeOf, type Phase, type Preset, type PreviewCheck, type PreviewRefusal, type ProcessMarkdown, type ProcessMarkdownOptions, type ProcessResult, type ProcessedMarkdown, type RenderHtml, type ResolveConfig, type ResolvedAudit, type ResolvedAuth, type ResolvedCollection, type ResolvedConfig, type ResolvedSite, type RuleDefinition, type RunContractsInput, SIGNATURE_HEADER, type SchemaOutput, type Scope, type Severity, type SiteDefinition, type SiteDefinitionData, type SiteDefinitionInput, type SiteDescription, type SiteEvent, TIMESTAMP_HEADER, type TaggedEntry, type Verdict, type Violation, WebhookCheck, schemas_d_exports as schemas, signWebhook, verifyWebhook };

package/dist/index.mjs

@@ -1,4 +1,5 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
+import { EVENT_ID_HEADER, SIGNATURE_HEADER, TIMESTAMP_HEADER, signWebhook, verifyWebhook } from "./webhooks.mjs";
 import * as z from "zod";
 import { Validator } from "@cfworker/json-schema";
 //#region src/config/define.ts
@@ -252,6 +253,60 @@ function readAudit(path, raw, problems) {
 	};
 }
 //#endregion
+//#region src/config/media.ts
+/** The formats a site may convert its images to, or keep them as they came (ADR-038). */
+const MEDIA_FORMATS = [
+	"webp",
+	"avif",
+	"original"
+];
+/** The narrowest an image may be scaled down to: smaller would blur on every screen. */
+const MEDIA_MIN_WIDTH = 320;
+/** The widest: past it the binding's area limit comes first, and no page shows more. */
+const MEDIA_MAX_WIDTH = 8192;
+/** What a site that says nothing gets: WebP at 85, and nothing wider than 2400 pixels. */
+const DEFAULT_MEDIA = {
+	format: "webp",
+	quality: 85,
+	maxWidth: 2400
+};
+const FIX = "Declare it as { format: \"webp\", quality: 85, maxWidth: 2400 }, or remove it.";
+/** How a site converts the images it receives (ADR-038). */
+function readMedia(path, raw, problems) {
+	if (raw === void 0 || raw === null) return DEFAULT_MEDIA;
+	if (!isRecord$4(raw)) {
+		problems.add(path, wrongType(raw, "an object"), FIX);
+		return DEFAULT_MEDIA;
+	}
+	let { format, quality, maxWidth } = DEFAULT_MEDIA;
+	const rawFormat = raw["format"];
+	if (rawFormat !== void 0) {
+		if (MEDIA_FORMATS.some((candidate) => candidate === rawFormat)) format = rawFormat;
+		else problems.add(keyPath(path, "format"), wrongType(rawFormat, "\"webp\", \"avif\" or \"original\""), "Use \"webp\" or \"avif\" to convert the images a site receives, or \"original\" to keep them as they came.");
+	}
+	const rawQuality = raw["quality"];
+	if (rawQuality !== void 0) {
+		if (isWhole(rawQuality) && rawQuality >= 1 && rawQuality <= 100) quality = rawQuality;
+		else problems.add(keyPath(path, "quality"), `${show(rawQuality)} is not a whole number from 1 to 100`, "Give the quality of photographs, 85 by default; PNG images are always kept lossless.");
+	}
+	const rawWidth = raw["maxWidth"];
+	if (rawWidth !== void 0) {
+		if (isWhole(rawWidth) && rawWidth >= 320 && rawWidth <= 8192) maxWidth = rawWidth;
+		else problems.add(keyPath(path, "maxWidth"), `${show(rawWidth)} is not a whole number of pixels from 320 to ${MEDIA_MAX_WIDTH}`, "Give the widest an image may be; a wider one is scaled down, never up.");
+	}
+	return {
+		format,
+		quality,
+		maxWidth
+	};
+}
+function isWhole(value) {
+	return typeof value === "number" && Number.isInteger(value);
+}
+function show(value) {
+	return typeof value === "number" ? String(value) : wrongType(value, "a number");
+}
+//#endregion
 //#region src/config/constants.ts
 /** The largest Markdown file a collection accepts when its config does not say, 512 KiB. */
 const DEFAULT_MAX_MARKDOWN_BYTES = 524288;
@@ -1933,7 +1988,8 @@ function readSite(key, raw, problems) {
 		url,
 		cors: readCors(keyPath(path, "cors"), raw["cors"], problems),
 		events: readEvents(keyPath(path, "events"), raw["events"], url, problems),
-		audit: readAudit(keyPath(path, "audit"), raw["audit"], problems)
+		audit: readAudit(keyPath(path, "audit"), raw["audit"], problems),
+		media: readMedia(keyPath(path, "media"), raw["media"], problems)
 	};
 }
 function readSites(raw, problems) {
@@ -2028,7 +2084,8 @@ const OPERATION_AUDIT_ACTIONS = [
 	"create_site",
 	"delete_site",
 	"restore_site",
-	"make_webhook_secret"
+	"make_webhook_secret",
+	"upload_asset"
 ];
 /** What people do outside the operations: their tokens, members, passkeys, sessions and apps. */
 const IDENTITY_AUDIT_ACTIONS = [
@@ -2125,6 +2182,11 @@ const siteDefinitionData = z.strictObject({
 		ipAddresses: "off",
 		retentionDays: null
 	}).describe("What the activity log of the site keeps (ADR-037). Only an owner should change it."),
+	media: z.strictObject({
+		format: z.enum(MEDIA_FORMATS).default(DEFAULT_MEDIA.format).describe("What JPEG, PNG and GIF images become when they arrive: \"webp\", \"avif\", or \"original\" to keep them as they came. SVG is never converted."),
+		quality: z.number().int().min(1).max(100).default(DEFAULT_MEDIA.quality).describe("The quality of photographs, 1 to 100. PNG images are always kept lossless."),
+		maxWidth: z.number().int().min(320).max(MEDIA_MAX_WIDTH).default(DEFAULT_MEDIA.maxWidth).describe("The widest an image is kept, in pixels; a wider one is scaled down, never up.")
+	}).default({ ...DEFAULT_MEDIA }).describe("How the site converts the images it receives (ADR-038)."),
 	collections: z.record(z.string(), collectionDefinitionData)
 });
 //#endregion
@@ -2272,7 +2334,8 @@ function compileSite(path, site, problems) {
 			})),
 			...site.events.indexNow === null ? {} : { indexNow: site.events.indexNow }
 		},
-		audit: site.audit
+		audit: site.audit,
+		media: site.media
 	};
 }
 /** The definitions of the sites, read from D1 as JSON, checked and resolved. */
@@ -2501,6 +2564,11 @@ function sitePreset(preset, locales, defaultLocale) {
 			ipAddresses: "off",
 			retentionDays: null
 		},
+		media: {
+			format: "webp",
+			quality: 85,
+			maxWidth: 2400
+		},
 		collections
 	};
 }
@@ -2545,6 +2613,7 @@ var HollwareError = class extends Error {
 const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
 /** The kinds of ids and their prefixes. A new kind adds its prefix here. */
 const ID_PREFIXES = {
+	asset: "ast",
 	auditLine: "aud",
 	challenge: "chl",
 	delivery: "dlv",
@@ -2691,7 +2760,7 @@ const ALERT_TYPES = [
 	"warning",
 	"caution"
 ];
-const text = (value) => typeof value === "string";
+const text$1 = (value) => typeof value === "string";
 const exactly = (...allowed) => (value) => typeof value === "string" && allowed.includes(value);
 const matching = (pattern) => (value) => typeof value === "string" && pattern.test(value);
 /** Only `language-*` classes, which is what a fenced code block carries. */
@@ -2708,20 +2777,20 @@ const alignment = /* @__PURE__ */ new Map([["style", exactly("text-align:left",
 * and markdown-it add themselves, so a document the parser writes passes its own rules.
 */
 const ATTRIBUTE_RULES = /* @__PURE__ */ new Map([
-	["a", /* @__PURE__ */ new Map([["href", text], ["title", text]])],
+	["a", /* @__PURE__ */ new Map([["href", text$1], ["title", text$1]])],
 	["img", /* @__PURE__ */ new Map([
-		["src", text],
-		["alt", text],
-		["title", text],
-		["width", text],
-		["height", text]
+		["src", text$1],
+		["alt", text$1],
+		["title", text$1],
+		["width", text$1],
+		["height", text$1]
 	])],
 	["code", /* @__PURE__ */ new Map([["class", languageClasses]])],
 	["pre", /* @__PURE__ */ new Map([
-		["language", text],
-		["filename", text],
+		["language", text$1],
+		["filename", text$1],
 		["highlights", lineNumbers],
-		["meta", text]
+		["meta", text$1]
 	])],
 	["ol", /* @__PURE__ */ new Map([["start", matching(/^\d{1,9}$/)]])],
 	["ul", /* @__PURE__ */ new Map([["class", exactly("contains-task-list")]])],
@@ -2811,7 +2880,11 @@ const LINK_SCHEMES = /* @__PURE__ */ new Set([
 	"https",
 	"mailto"
 ]);
-const IMAGE_SCHEMES = /* @__PURE__ */ new Set(["http", "https"]);
+const IMAGE_SCHEMES = /* @__PURE__ */ new Set([
+	"http",
+	"https",
+	"asset"
+]);
 /**
 * Whether a link or an image may point there. A relative URL (a path, `#anchor`, `?query` or
 * `//host/path`) is always safe: it keeps the scheme of the page. Of the schemes, links may use
@@ -4088,6 +4161,158 @@ const siteDescription = z.object({
 	collections: z.array(collectionDescription)
 });
 //#endregion
+//#region src/media/index.ts
+/** The kinds of image Hollware takes, by media type. */
+const IMAGE_FORMATS = [
+	"image/jpeg",
+	"image/png",
+	"image/webp",
+	"image/avif",
+	"image/gif",
+	"image/svg+xml"
+];
+/** The largest file `upload_asset` takes, in bytes: the binding takes 20 MB, this keeps room. */
+const MAX_ASSET_BYTES = 10485760;
+/** The extension a format is served and exported with. */
+const EXTENSIONS = {
+	"image/jpeg": "jpg",
+	"image/png": "png",
+	"image/webp": "webp",
+	"image/avif": "avif",
+	"image/gif": "gif",
+	"image/svg+xml": "svg"
+};
+const startsWith = (bytes, at, expected) => expected.every((byte, index) => bytes[at + index] === byte);
+const ascii = (text) => Array.from({ length: text.length }, (_, at) => text.charCodeAt(at));
+/**
+* The format of a file, read from its bytes and never from its name or a header: `null` for
+* anything else. An SVG is text that opens on `<svg` or on an XML declaration followed by one.
+*/
+function sniffImage(bytes) {
+	if (startsWith(bytes, 0, [
+		255,
+		216,
+		255
+	])) return "image/jpeg";
+	if (startsWith(bytes, 0, [
+		137,
+		80,
+		78,
+		71,
+		13,
+		10,
+		26,
+		10
+	])) return "image/png";
+	if (startsWith(bytes, 0, ascii("RIFF")) && startsWith(bytes, 8, ascii("WEBP"))) return "image/webp";
+	if (startsWith(bytes, 4, ascii("ftyp")) && /^avi[fs]$/.test(text(bytes.subarray(8, 12)))) return "image/avif";
+	if (startsWith(bytes, 0, ascii("GIF87a")) || startsWith(bytes, 0, ascii("GIF89a"))) return "image/gif";
+	const head = text(bytes.subarray(0, 512)).replace(BOM, "").trimStart();
+	if (/^<svg[\s>/]/i.test(head) || /^<\?xml[^>]*\?>\s*(<!--[\s\S]*?-->\s*)*<svg[\s>/]/i.test(head)) return "image/svg+xml";
+	return null;
+}
+/** A byte order mark, which an editor may put before an SVG's first tag. */
+const BOM = new RegExp(`^${String.fromCodePoint(65279)}`);
+function text(bytes) {
+	return new TextDecoder("utf-8", { fatal: false }).decode(bytes);
+}
+const SVG_FIX = "Export the SVG again without scripts, embedded HTML, event handlers or external references (any SVG optimizer does it), or upload it as PNG.";
+const SVG_REFUSALS = [
+	{
+		pattern: /<!DOCTYPE|<!ENTITY/i,
+		reason: "it declares a DOCTYPE or an entity"
+	},
+	{
+		pattern: /<script[\s>/]/i,
+		reason: "it holds a <script>"
+	},
+	{
+		pattern: /<foreignObject[\s>/]/i,
+		reason: "it holds a <foreignObject>, which embeds HTML"
+	},
+	{
+		pattern: /<(?:iframe|embed|object|audio|video)[\s>/]/i,
+		reason: "it embeds another document"
+	},
+	{
+		pattern: /\son[a-z]+\s*=/i,
+		reason: "it has an event handler (an on… attribute)"
+	},
+	{
+		pattern: /\bjavascript\s*:|\bdata\s*:/i,
+		reason: "it holds a javascript: or data: URL"
+	},
+	{
+		pattern: /(?:xlink:)?href\s*=\s*["']?\s*(?!#)[^"'\s>]/i,
+		reason: "it links outside the file (an href that does not start with #)"
+	},
+	{
+		pattern: /@import|url\(\s*["']?\s*(?!["'\s#])/i,
+		reason: "its styles load something from outside"
+	}
+];
+/** `null` when an SVG holds nothing that can run or reach out, else the first thing that can. */
+function checkSvg(source) {
+	for (const { pattern, reason } of SVG_REFUSALS) if (pattern.test(source)) return {
+		reason,
+		fix: SVG_FIX
+	};
+	return null;
+}
+/**
+* What a file of `format`, `width` pixels wide (null for an SVG), becomes under `media`: JPEG,
+* PNG and GIF become the site's format; a WebP or an AVIF keeps its own and is only scaled down
+* when it is wider than the site allows; `original` and SVG keep every file as it came.
+*/
+function conversionOf(format, width, media) {
+	if (format === "image/svg+xml" || media.format === "original") return null;
+	const tooWide = width !== null && width > media.maxWidth;
+	const modern = format === "image/webp" || format === "image/avif";
+	if (modern && !tooWide) return null;
+	return {
+		format: modern ? format : media.format === "avif" ? "image/avif" : "image/webp",
+		quality: format === "image/png" ? 100 : media.quality,
+		anim: true,
+		...tooWide ? { width: media.maxWidth } : {}
+	};
+}
+/** The id of an asset, from the SHA-256 of its original bytes: the same file is the same asset. */
+function assetIdOf(sha256Hex) {
+	return `ast_${sha256Hex.slice(0, 26)}`;
+}
+/** What content writes to name an asset: `asset:ast_…`. */
+const ASSET_SCHEME = "asset:";
+const ASSET_REFERENCE = /^asset:(ast_[0-9a-f]{26})$/;
+/** The id an `asset:` reference names, or `null` when the value is no such reference. */
+function assetIdIn(value) {
+	return ASSET_REFERENCE.exec(value.trim())?.[1] ?? null;
+}
+/**
+* A copy of a value (a frontmatter, a document) with every string that is an `asset:` reference
+* replaced by the URL `urlOf` gives its id. Everything else is copied as it is.
+*/
+function resolveAssetReferences(value, urlOf) {
+	const visit = (node) => {
+		if (typeof node === "string") {
+			const id = assetIdIn(node);
+			return id === null ? node : urlOf(id);
+		}
+		if (Array.isArray(node)) return node.map(visit);
+		if (typeof node === "object" && node !== null) {
+			const copy = {};
+			for (const [key, child] of Object.entries(node)) Object.defineProperty(copy, key, {
+				value: visit(child),
+				enumerable: true,
+				writable: true,
+				configurable: true
+			});
+			return copy;
+		}
+		return node;
+	};
+	return visit(value);
+}
+//#endregion
 //#region src/operations/types.ts
 /** Declares an operation spec, keeping the literal types of its name and schemas. */
 function defineOperation(spec) {
@@ -4572,7 +4797,9 @@ const structureChange = z.object({
 	version: z.number().int().optional().describe("The version of the structure now."),
 	problems: z.array(problem).optional().describe("With invalid: every problem, each with its fix."),
 	impact: impact.optional().describe("With needs_confirmation: what the change would do."),
-	currentVersion: z.number().int().optional().describe("With conflict: the version to read again.")
+	currentVersion: z.number().int().optional().describe("With conflict: the version to read again."),
+	message: z.string().optional().describe("With conflict: what happened."),
+	fix: z.string().optional().describe("With conflict: what to do next.")
 });
 const STRUCTURE_OUTCOMES = {
 	updated: { isError: false },
@@ -4692,6 +4919,109 @@ const restoreSite = defineOperation({
 		not_found: { isError: true }
 	}
 });
+const makeWebhookSecret = defineOperation({
+	name: "make_webhook_secret",
+	title: "Make the secret of a webhook",
+	description: "Makes a new secret for a webhook of the site that names no Worker secret of its own, keeps it sealed, and answers it once: give it to the receiver, which checks each delivery's signature with it. A new one replaces the old at once. unavailable when the deployment has no HOLLWARE_SECRET to seal it with.",
+	input: z.strictObject({ webhook: z.string().min(1).describe("The name of the webhook, as the definition of the site has it.") }),
+	output: z.object({
+		outcome: z.enum([
+			"made",
+			"not_found",
+			"unavailable"
+		]),
+		secret: z.string().optional().describe("With made: the secret, shown this once.")
+	}),
+	scopes: ["schema:admin"],
+	effect: "write",
+	outcomes: {
+		made: { isError: false },
+		not_found: { isError: true },
+		unavailable: { isError: true }
+	}
+});
+const assetId = z.string().regex(/^ast_[0-9a-f]{26}$/).describe("The id of an asset, such as ast_3f1c… (26 hexadecimal characters).");
+/** An asset as the operations answer it. */
+const asset = z.object({
+	id: assetId,
+	reference: z.string().describe("What content writes to show it: img: asset:ast_… or ![alt](asset:ast_…)."),
+	url: z.string().describe("Where the Worker serves it, to anyone, cached for a year."),
+	format: z.enum(IMAGE_FORMATS).describe("What it is served as."),
+	width: z.number().int().nullable().describe("In pixels; null for an SVG."),
+	height: z.number().int().nullable(),
+	bytes: z.number().int().describe("The size of the file served."),
+	originalFormat: z.enum(IMAGE_FORMATS).describe("What it was sent as."),
+	originalBytes: z.number().int(),
+	alt: z.string().describe("What it shows, for whoever cannot see it."),
+	filename: z.string().describe("The name it was sent with."),
+	createdAt: z.string()
+});
+/** Base64 of at most MAX_ASSET_BYTES, with its padding: four characters for every three bytes. */
+const MAX_BASE64 = Math.ceil(MAX_ASSET_BYTES / 3) * 4;
+const uploadAsset = defineOperation({
+	name: "upload_asset",
+	title: "Upload an image",
+	description: "Uploads an image to the site: JPEG, PNG, WebP, AVIF, GIF or SVG, at most 10 MB, sent in base64. What it is comes from its bytes, never from its name. The site's media setting converts it once (to WebP at 85 by default; PNG lossless; GIF with its frames; nothing wider than its maxWidth), and an SVG is kept as it is when nothing in it can run, or refused with what to remove. The same file uploaded again answers exists with the same asset. Write its reference in content: img: asset:ast_… in the frontmatter, or ![alt](asset:ast_…) in Markdown.",
+	input: z.strictObject({
+		filename: z.string().min(1).max(200).describe("Its name, such as continuum.png."),
+		alt: z.string().min(1).max(500).describe("What the image shows, for whoever cannot see it: required."),
+		data: z.string().min(1).max(MAX_BASE64).describe("The file, in base64.")
+	}),
+	output: z.object({
+		outcome: z.enum([
+			"created",
+			"exists",
+			"refused",
+			"unavailable"
+		]),
+		asset: asset.optional(),
+		problem: z.object({
+			message: z.string(),
+			fix: z.string()
+		}).optional().describe("With refused or unavailable: what is wrong, and what to do.")
+	}),
+	scopes: ["content:write"],
+	effect: "write",
+	outcomes: {
+		created: { isError: false },
+		exists: { isError: false },
+		refused: { isError: true },
+		unavailable: { isError: true }
+	}
+});
+const listAssets = defineOperation({
+	name: "list_assets",
+	title: "List the images of the site",
+	description: "Lists the images of the site, newest first, with their reference, URL, size and alt. Pass the nextCursor of an answer as cursor to get the next page.",
+	input: z.strictObject({
+		limit: z.number().int().min(1).max(100).default(20),
+		cursor: z.string().min(1).optional()
+	}),
+	output: z.object({
+		outcome: z.enum(["ok"]),
+		assets: z.array(asset),
+		nextCursor: z.string().nullable().describe("The cursor of the next page, or null.")
+	}),
+	scopes: ["content:read"],
+	effect: "read",
+	outcomes: { ok: { isError: false } }
+});
+const getAsset = defineOperation({
+	name: "get_asset",
+	title: "Get an image",
+	description: "Gets an image of the site by its id: its reference, URL, size and alt. The file as it was uploaded is at GET /v1/assets/<id>/original, with a personal token.",
+	input: z.strictObject({ id: assetId }),
+	output: z.object({
+		outcome: z.enum(["ok", "not_found"]),
+		asset: asset.optional()
+	}),
+	scopes: ["content:read"],
+	effect: "read",
+	outcomes: {
+		ok: { isError: false },
+		not_found: { isError: true }
+	}
+});
 /** Every operation, sorted by name: the order of `tools/list`. */
 const OPERATIONS = [
 	approveReview,
@@ -4702,32 +5032,14 @@ const OPERATIONS = [
 	deleteEntry,
 	deleteSite,
 	describeSite,
+	getAsset,
 	getEntry,
 	getStructure,
 	getTranslations,
+	listAssets,
 	listEntries,
 	listReviews,
-	defineOperation({
-		name: "make_webhook_secret",
-		title: "Make the secret of a webhook",
-		description: "Makes a new secret for a webhook of the site that names no Worker secret of its own, keeps it sealed, and answers it once: give it to the receiver, which checks each delivery's signature with it. A new one replaces the old at once. unavailable when the deployment has no HOLLWARE_SECRET to seal it with.",
-		input: z.strictObject({ webhook: z.string().min(1).describe("The name of the webhook, as the definition of the site has it.") }),
-		output: z.object({
-			outcome: z.enum([
-				"made",
-				"not_found",
-				"unavailable"
-			]),
-			secret: z.string().optional().describe("With made: the secret, shown this once.")
-		}),
-		scopes: ["schema:admin"],
-		effect: "write",
-		outcomes: {
-			made: { isError: false },
-			not_found: { isError: true },
-			unavailable: { isError: true }
-		}
-	}),
+	makeWebhookSecret,
 	publish,
 	requestChanges,
 	requestReview,
@@ -4738,6 +5050,7 @@ const OPERATIONS = [
 	unpublish,
 	updateDraft,
 	updateSite,
+	uploadAsset,
 	validate
 ];
 //#endregion
@@ -4808,64 +5121,6 @@ async function hashPersonalToken(token) {
 	return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
 }
 //#endregion
-//#region src/webhooks.ts
-/**
-* The signature of Hollware's webhooks (ADR-025), for the Worker that sends them and for whoever
-* receives them: HMAC-SHA256 of `<timestamp>.<body>` with the webhook's secret, sent as
-* `hollware-signature: v1=<hex>` with `hollware-timestamp` (seconds since the epoch) and
-* `hollware-event-id`. Web Crypto only, so it runs in any runtime.
-*/
-const SIGNATURE_HEADER = "hollware-signature";
-const TIMESTAMP_HEADER = "hollware-timestamp";
-const EVENT_ID_HEADER = "hollware-event-id";
-/** How far a timestamp may be from the receiver's clock, by default: five minutes. */
-const TOLERANCE_SECONDS = 300;
-const encoder$1 = new TextEncoder();
-async function hmac(secret, text) {
-	const key = await crypto.subtle.importKey("raw", encoder$1.encode(secret), {
-		name: "HMAC",
-		hash: "SHA-256"
-	}, false, ["sign"]);
-	return [...new Uint8Array(await crypto.subtle.sign("HMAC", key, encoder$1.encode(text)))].map((byte) => byte.toString(16).padStart(2, "0")).join("");
-}
-/** The value of `hollware-signature` for a body sent at `timestamp` (seconds). */
-async function signWebhook(secret, timestamp, body) {
-	return `v1=${await hmac(secret, `${timestamp}.${body}`)}`;
-}
-/** Compares two strings in time that does not depend on where they differ. */
-function sameText(a, b) {
-	if (a.length !== b.length) return false;
-	let difference = 0;
-	for (let index = 0; index < a.length; index++) difference |= a.charCodeAt(index) ^ b.charCodeAt(index);
-	return difference === 0;
-}
-/** The id of the event a body holds, or `null` when it holds none. */
-function eventIdOf(body) {
-	try {
-		const value = JSON.parse(body);
-		const id = typeof value === "object" && value !== null ? Reflect.get(value, "id") : null;
-		return typeof id === "string" && id !== "" ? id : null;
-	} catch {
-		return null;
-	}
-}
-/**
-* Whether a request is a webhook of Hollware: its signature matches the body and the secret, and
-* its timestamp is within the tolerance, so a captured request cannot be replayed later; with
-* `isNew`, also that its event was not received before, so it cannot be replayed sooner either.
-*/
-async function verifyWebhook(check) {
-	const signature = check.headers.get(SIGNATURE_HEADER);
-	const timestamp = Number(check.headers.get(TIMESTAMP_HEADER));
-	if (signature === null || !Number.isInteger(timestamp)) return false;
-	const now = check.now ?? Math.floor(Date.now() / 1e3);
-	if (Math.abs(now - timestamp) > (check.toleranceSeconds ?? TOLERANCE_SECONDS)) return false;
-	if (!sameText(signature, await signWebhook(check.secret, timestamp, check.body))) return false;
-	if (check.isNew === void 0) return true;
-	const id = eventIdOf(check.body);
-	return id !== null && await check.isNew(id);
-}
-//#endregion
 //#region src/preview.ts
 /**
 * The preview token (T-103 of docs/security/threat-model.md): a signed, stateless proof that a person of a site may read the
@@ -5117,4 +5372,4 @@ function tagsOfSiteChange(collections, locales) {
 //#region src/index.ts
 const name = "@hollware/core";
 //#endregion
-export { AUDIT_ACTIONS, AUDIT_ACTOR_KINDS, AUDIT_OUTCOMES, AUDIT_RETENTION_MAX_DAYS, AUDIT_RETENTION_MIN_DAYS, BUILT_IN_CONTRACT_IDS, CATALOG, CHUNKER_VERSION, CHUNK_LIMITS, COMARK_VERSION, ConfigError, DEFAULT_AUDIT, DEFAULT_MAX_MARKDOWN_BYTES, ERROR_CODES, EVENT_ID_HEADER, EVERY_LOCALE, HollwareError, IDENTITY_AUDIT_ACTIONS, ID_PREFIXES, INDEXNOW_KEY, MAX_MARKDOWN_BYTES_CEILING, OPERATIONS, OPERATION_AUDIT_ACTIONS, PERSONAL_TOKEN_PREFIX, PERSONAL_TOKEN_TTL_DAYS, PIPELINE_VERSION, PRESETS, PREVIEW_QUERY_PARAM, PREVIEW_SECRET_MIN_LENGTH, PREVIEW_TOKEN_PREFIX, PREVIEW_TTL_SECONDS, READ_TOKEN_PREFIX, REFUSAL_CONTRACT_IDS, SCOPES, SIGNATURE_HEADER, SITE_KEY_MAX_LENGTH, SITE_KEY_PATTERN, SITE_TAG, TIMESTAMP_HEADER, approveReview, canSignPreviews, canonicalJson, catalogRule, chunksOf, collectionDefinitionData, collectionPreset, commentReview, compileSites, componentDefinitionData, contentStats, contracts, createDraft, defineCollection, defineComponent, defineConfig, defineContract, defineOperation, definitionsFromConfig, deleteEntry, describeBuiltInContracts, describeCatalog, describeContract, describeResolvedSite, describeSite, describedSchemaOf, entryEvent, entryTag, generatePersonalToken, generateReadToken, getEntry, getTranslations, groupTag, hashPersonalToken, hollwareEvent, isAuditAction, isBuiltInContract, isId, isPersonalToken, isReadToken, isScope, isSiteKey, listEntries, listReviews, listTag, makePreviewToken, name, newId, parseHollwareEvent, processMarkdown, publish, renderHtml, requestChanges, requestReview, resolveConfig, restoreEntry, routesFor, ruleDefinition, runContracts, schemas_exports as schemas, search, signWebhook, siteDefinitionData, siteEvent, sitePreset, sizeLimitViolation, tagsOfChange, tagsOfEntries, tagsOfSiteChange, ulid, uniqueSlugViolation, uniqueTranslationViolation, unpublish, updateDraft, validate, verifyPreviewToken, verifyWebhook, webhookDefinition };
+export { ASSET_SCHEME, AUDIT_ACTIONS, AUDIT_ACTOR_KINDS, AUDIT_OUTCOMES, AUDIT_RETENTION_MAX_DAYS, AUDIT_RETENTION_MIN_DAYS, BUILT_IN_CONTRACT_IDS, CATALOG, CHUNKER_VERSION, CHUNK_LIMITS, COMARK_VERSION, ConfigError, DEFAULT_AUDIT, DEFAULT_MAX_MARKDOWN_BYTES, DEFAULT_MEDIA, ERROR_CODES, EVENT_ID_HEADER, EVERY_LOCALE, EXTENSIONS, HollwareError, IDENTITY_AUDIT_ACTIONS, ID_PREFIXES, IMAGE_FORMATS, INDEXNOW_KEY, MAX_ASSET_BYTES, MAX_MARKDOWN_BYTES_CEILING, MEDIA_FORMATS, MEDIA_MAX_WIDTH, MEDIA_MIN_WIDTH, OPERATIONS, OPERATION_AUDIT_ACTIONS, PERSONAL_TOKEN_PREFIX, PERSONAL_TOKEN_TTL_DAYS, PIPELINE_VERSION, PRESETS, PREVIEW_QUERY_PARAM, PREVIEW_SECRET_MIN_LENGTH, PREVIEW_TOKEN_PREFIX, PREVIEW_TTL_SECONDS, READ_TOKEN_PREFIX, REFUSAL_CONTRACT_IDS, SCOPES, SIGNATURE_HEADER, SITE_KEY_MAX_LENGTH, SITE_KEY_PATTERN, SITE_TAG, TIMESTAMP_HEADER, approveReview, assetIdIn, assetIdOf, canSignPreviews, canonicalJson, catalogRule, checkSvg, chunksOf, collectionDefinitionData, collectionPreset, commentReview, compileSites, componentDefinitionData, contentStats, contracts, conversionOf, createDraft, defineCollection, defineComponent, defineConfig, defineContract, defineOperation, definitionsFromConfig, deleteEntry, describeBuiltInContracts, describeCatalog, describeContract, describeResolvedSite, describeSite, describedSchemaOf, entryEvent, entryTag, generatePersonalToken, generateReadToken, getAsset, getEntry, getTranslations, groupTag, hashPersonalToken, hollwareEvent, isAuditAction, isBuiltInContract, isId, isPersonalToken, isReadToken, isScope, isSiteKey, listAssets, listEntries, listReviews, listTag, makePreviewToken, name, newId, parseHollwareEvent, processMarkdown, publish, renderHtml, requestChanges, requestReview, resolveAssetReferences, resolveConfig, restoreEntry, routesFor, ruleDefinition, runContracts, schemas_exports as schemas, search, signWebhook, siteDefinitionData, siteEvent, sitePreset, sizeLimitViolation, sniffImage, tagsOfChange, tagsOfEntries, tagsOfSiteChange, ulid, uniqueSlugViolation, uniqueTranslationViolation, unpublish, updateDraft, uploadAsset, validate, verifyPreviewToken, verifyWebhook, webhookDefinition };

package/dist/webhooks.d.mts

@@ -0,0 +1,36 @@
+//#region src/webhooks.d.ts
+/**
+ * The signature of Hollware's webhooks (ADR-025), for the Worker that sends them and for whoever
+ * receives them: HMAC-SHA256 of `<timestamp>.<body>` with the webhook's secret, sent as
+ * `hollware-signature: v1=<hex>` with `hollware-timestamp` (seconds since the epoch) and
+ * `hollware-event-id`. Web Crypto only, so it runs in any runtime.
+ */
+export declare const SIGNATURE_HEADER = "hollware-signature";
+export declare const TIMESTAMP_HEADER = "hollware-timestamp";
+export declare const EVENT_ID_HEADER = "hollware-event-id";
+/** The value of `hollware-signature` for a body sent at `timestamp` (seconds). */
+export declare function signWebhook(secret: string, timestamp: number, body: string): Promise<string>;
+export interface WebhookCheck {
+  readonly secret: string;
+  /** The raw body, as received: a parsed and re-serialized body no longer matches. */
+  readonly body: string;
+  readonly headers: Headers;
+  /** Now, in seconds since the epoch; the system clock when absent. */
+  readonly now?: number;
+  readonly toleranceSeconds?: number;
+  /**
+   * Whether the receiver sees this event for the first time, given its id, and records it (T-67):
+   * a request captured and sent again within the tolerance is then refused. The id is read from
+   * the signed body, never from `hollware-event-id`, which no signature covers. A retry of a
+   * delivery carries the same id, so a receiver that records an id only once it has handled the
+   * event lets a failed delivery be retried. Keep each id for longer than the tolerance.
+   */
+  readonly isNew?: (eventId: string) => boolean | Promise<boolean>;
+}
+/**
+ * Whether a request is a webhook of Hollware: its signature matches the body and the secret, and
+ * its timestamp is within the tolerance, so a captured request cannot be replayed later; with
+ * `isNew`, also that its event was not received before, so it cannot be replayed sooner either.
+ */
+export declare function verifyWebhook(check: WebhookCheck): Promise<boolean>;
+//#endregion

package/dist/webhooks.mjs

@@ -0,0 +1,59 @@
+//#region src/webhooks.ts
+/**
+* The signature of Hollware's webhooks (ADR-025), for the Worker that sends them and for whoever
+* receives them: HMAC-SHA256 of `<timestamp>.<body>` with the webhook's secret, sent as
+* `hollware-signature: v1=<hex>` with `hollware-timestamp` (seconds since the epoch) and
+* `hollware-event-id`. Web Crypto only, so it runs in any runtime.
+*/
+const SIGNATURE_HEADER = "hollware-signature";
+const TIMESTAMP_HEADER = "hollware-timestamp";
+const EVENT_ID_HEADER = "hollware-event-id";
+/** How far a timestamp may be from the receiver's clock, by default: five minutes. */
+const TOLERANCE_SECONDS = 300;
+const encoder = new TextEncoder();
+async function hmac(secret, text) {
+	const key = await crypto.subtle.importKey("raw", encoder.encode(secret), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign"]);
+	return [...new Uint8Array(await crypto.subtle.sign("HMAC", key, encoder.encode(text)))].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/** The value of `hollware-signature` for a body sent at `timestamp` (seconds). */
+async function signWebhook(secret, timestamp, body) {
+	return `v1=${await hmac(secret, `${timestamp}.${body}`)}`;
+}
+/** Compares two strings in time that does not depend on where they differ. */
+function sameText(a, b) {
+	if (a.length !== b.length) return false;
+	let difference = 0;
+	for (let index = 0; index < a.length; index++) difference |= a.charCodeAt(index) ^ b.charCodeAt(index);
+	return difference === 0;
+}
+/** The id of the event a body holds, or `null` when it holds none. */
+function eventIdOf(body) {
+	try {
+		const value = JSON.parse(body);
+		const id = typeof value === "object" && value !== null ? Reflect.get(value, "id") : null;
+		return typeof id === "string" && id !== "" ? id : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Whether a request is a webhook of Hollware: its signature matches the body and the secret, and
+* its timestamp is within the tolerance, so a captured request cannot be replayed later; with
+* `isNew`, also that its event was not received before, so it cannot be replayed sooner either.
+*/
+async function verifyWebhook(check) {
+	const signature = check.headers.get(SIGNATURE_HEADER);
+	const timestamp = Number(check.headers.get(TIMESTAMP_HEADER));
+	if (signature === null || !Number.isInteger(timestamp)) return false;
+	const now = check.now ?? Math.floor(Date.now() / 1e3);
+	if (Math.abs(now - timestamp) > (check.toleranceSeconds ?? TOLERANCE_SECONDS)) return false;
+	if (!sameText(signature, await signWebhook(check.secret, timestamp, check.body))) return false;
+	if (check.isNew === void 0) return true;
+	const id = eventIdOf(check.body);
+	return id !== null && await check.isNew(id);
+}
+//#endregion
+export { EVENT_ID_HEADER, SIGNATURE_HEADER, TIMESTAMP_HEADER, signWebhook, verifyWebhook };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hollware/core",
-  "version": "1.0.0-rc.0",
+  "version": "1.0.0-rc.2",
   "description": "Contracts, operation specs, schemas and the Markdown pipeline of Hollware. No Cloudflare dependencies.",
   "homepage": "https://hollware.com",
   "bugs": {
@@ -22,6 +22,10 @@
       "types": "./dist/index.d.mts",
       "default": "./dist/index.mjs"
     },
+    "./webhooks": {
+      "types": "./dist/webhooks.d.mts",
+      "default": "./dist/webhooks.mjs"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {