@hollware/core 0.10.0 → 1.0.0-rc.0

package/dist/index.d.mts

@@ -315,11 +315,18 @@ interface SiteDefinition {
       /** The Worker secret that signs; Hollware's own sealed one when it is left out. */
       readonly secret?: string;
     }[];
-    /** Tells IndexNow the URLs that changed; `key` names the Worker secret with the key. */
+    /** Tells IndexNow the URLs that changed; `key` is the key itself, which is public. */
     readonly indexNow?: {
       readonly key: string;
     };
   };
+  /** What the site's activity log keeps (ADR-037): no addresses, and forever, by default. */
+  readonly audit?: {
+    /** `hashed` keeps a keyed hash of the address of each request; `off` keeps nothing of it. */
+    readonly ipAddresses?: 'off' | 'hashed';
+    /** How many days a line is kept, 30 to 3650; `null` keeps the log as long as the site. */
+    readonly retentionDays?: number | null;
+  };
 }
 /** What `hollware.config.ts` exports. */
 interface HollwareConfig {
@@ -369,6 +376,12 @@ interface ResolvedSite {
     readonly origins: readonly string[];
   };
   readonly events: ResolvedEvents;
+  readonly audit: ResolvedAudit;
+}
+/** What the activity log of a site keeps (ADR-037). */
+interface ResolvedAudit {
+  readonly ipAddresses: 'off' | 'hashed';
+  readonly retentionDays: number | null;
 }
 /**
  * A webhook of a site. `secret` names the Worker secret that signs its deliveries; `null` when the
@@ -450,6 +463,14 @@ export declare class ConfigError extends Error {
  */
 export declare const INDEXNOW_KEY: RegExp;
 //#endregion
+//#region src/config/audit.d.ts
+/** The fewest days a site may keep its activity log for, when it sets a retention (ADR-037). */
+export declare const AUDIT_RETENTION_MIN_DAYS = 30;
+/** The most days a retention may be: ten years. Beyond that, keep it with no retention. */
+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/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;
@@ -1124,6 +1145,34 @@ export declare const SITE_KEY_MAX_LENGTH = 64;
 /** Whether a value is a site key: a string that fits `SITE_KEY_PATTERN` and is not too long. */
 export declare function isSiteKey(value: unknown): value is string;
 //#endregion
+//#region src/audit/index.d.ts
+/**
+ * The actions of the activity log (ADR-037). A line names one of these, and nothing else: a new
+ * 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'];
+/** 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). */
+'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',
+/** A refresh token was used again after it was spent, so its grant was revoked (T-34). */
+'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 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'];
+export type AuditOutcome = (typeof AUDIT_OUTCOMES)[number];
+/**
+ * Who acted: a person in the admin, a personal token, an app a person allowed through OAuth, or
+ * the deployment itself (its cron).
+ */
+export declare const AUDIT_ACTOR_KINDS: readonly ['user', 'token', 'oauth_client', 'system'];
+export type AuditActorKind = (typeof AUDIT_ACTOR_KINDS)[number];
+export declare function isAuditAction(value: string): value is AuditAction;
+//#endregion
 //#region src/structure/compile.d.ts
 /** The definitions of the sites, read from D1 as JSON, checked and resolved. */
 export declare function compileSites(definitions: Readonly<Record<string, unknown>>): ResolvedConfig;
@@ -1189,6 +1238,13 @@ export declare const siteDefinitionData: z.ZodObject<{
       key: z.ZodString;
     }, z.core.$strict>>>;
   }, z.core.$strict>>;
+  audit: z.ZodDefault<z.ZodObject<{
+    ipAddresses: z.ZodDefault<z.ZodEnum<{
+      hashed: "hashed";
+      off: "off";
+    }>>;
+    retentionDays: z.ZodDefault<z.ZodNullable<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>;
@@ -1263,6 +1319,8 @@ export declare const ERROR_CODES: readonly [
 'unknown_collection',
 /** The input names a locale the site does not have. */
 'unknown_locale',
+/** A preview link that has expired, or is not one Hollware made for this site (T-103). */
+'invalid_preview',
 /** The token lacks a scope the operation requires; the message names every missing scope. */
 'insufficient_scope',
 /** The answer would exceed the output cap. Hollware never truncates content. */
@@ -1293,6 +1351,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 auditLine: 'aud';
   readonly challenge: 'chl';
   readonly delivery: 'dlv';
   readonly embedding: 'emb';
@@ -2574,6 +2633,13 @@ export declare const OPERATIONS: readonly [OperationSpec<"approve_review", z.Zod
         key: z.ZodString;
       }, z.core.$strict>>>;
     }, z.core.$strict>>;
+    audit: z.ZodDefault<z.ZodObject<{
+      ipAddresses: z.ZodDefault<z.ZodEnum<{
+        hashed: "hashed";
+        off: "off";
+      }>>;
+      retentionDays: z.ZodDefault<z.ZodNullable<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>;
@@ -2849,6 +2915,13 @@ export declare const OPERATIONS: readonly [OperationSpec<"approve_review", z.Zod
         key: z.ZodString;
       }, z.core.$strict>>>;
     }, z.core.$strict>>;
+    audit: z.ZodDefault<z.ZodObject<{
+      ipAddresses: z.ZodDefault<z.ZodEnum<{
+        hashed: "hashed";
+        off: "off";
+      }>>;
+      retentionDays: z.ZodDefault<z.ZodNullable<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>;
@@ -3463,6 +3536,13 @@ export declare const OPERATIONS: readonly [OperationSpec<"approve_review", z.Zod
         key: z.ZodString;
       }, z.core.$strict>>>;
     }, z.core.$strict>>;
+    audit: z.ZodDefault<z.ZodObject<{
+      ipAddresses: z.ZodDefault<z.ZodEnum<{
+        hashed: "hashed";
+        off: "off";
+      }>>;
+      retentionDays: z.ZodDefault<z.ZodNullable<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>;
@@ -3615,13 +3695,76 @@ export interface WebhookCheck {
   /** 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.
+ * 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
+//#region src/preview.d.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
+ * latest revision of one entry, for one hour. A site that reads published content only (the
+ * binding of RPC, the read API) reads that entry's head instead when it presents one.
+ *
+ *   hw_prv_<payload>.<signature>
+ *
+ * The payload is base64url of `{ "s": site, "e": entryId, "x": expiresAtSeconds }`, and the
+ * signature the base64url HMAC-SHA256 of the payload text under a key that HKDF-SHA256 derives
+ * from the Worker secret `HOLLWARE_SECRET`, bound to the site. Nothing is stored: a token cannot
+ * be revoked, only wait out its hour, and rotating the secret ends every one.
+ */
+export declare const PREVIEW_TOKEN_PREFIX = "hw_prv_";
+/** The query parameter a site's page takes the token from. */
+export declare const PREVIEW_QUERY_PARAM = "hollware-preview";
+/** How long a token lasts, in seconds. */
+export declare const PREVIEW_TTL_SECONDS = 3600;
+/** The least characters of `HOLLWARE_SECRET` that Hollware signs anything with. */
+export declare const PREVIEW_SECRET_MIN_LENGTH = 32;
+/** Why a token was not accepted: for the log of the operator, never for the caller. */
+type PreviewRefusal = 'no_secret' | 'malformed' | 'signature' | 'site' | 'expired';
+type PreviewCheck = {
+  readonly ok: true;
+  readonly entryId: string;
+  readonly expiresAt: string;
+} | {
+  readonly ok: false;
+  readonly reason: PreviewRefusal;
+};
+/** Whether a Worker's secret can sign previews: present and long enough. */
+export declare function canSignPreviews(secret: string | undefined): secret is string;
+/** A token for one entry of one site, valid for `PREVIEW_TTL_SECONDS` from `now`. */
+export declare function makePreviewToken(input: {
+  readonly secret: string;
+  readonly site: string;
+  readonly entryId: string;
+  readonly now: Date;
+}): Promise<{
+  readonly token: string;
+  readonly expiresAt: string;
+}>;
+/**
+ * Checks a token for a site. The signature is verified (in constant time, by `crypto.subtle`)
+ * before the payload is parsed, under the key of the site that is asked: a token made for another
+ * site fails there. The entry the token names is the caller's to compare with the entry it read.
+ */
+export declare function verifyPreviewToken(input: {
+  readonly secret: string | undefined;
+  readonly site: string;
+  readonly token: string;
+  readonly now: Date;
+}): Promise<PreviewCheck>;
+//#endregion
 //#region src/events.d.ts
 /** A publish or an unpublish: the entry, and where it lives on the site. */
 export declare const entryEvent: z.ZodObject<{
@@ -3762,4 +3905,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 ProcessMarkdown, type ProcessMarkdownOptions, type ProcessResult, type ProcessedMarkdown, type RenderHtml, type ResolveConfig, 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, 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 };

package/dist/index.mjs

@@ -57,7 +57,7 @@ var Problems = class {
 //#endregion
 //#region src/config/values.ts
 /** A value with keys: not null, not an array. */
-function isRecord$3(value) {
+function isRecord$4(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 /** A string as the messages show it: quoted, with what could break a line escaped. */
@@ -137,7 +137,7 @@ function readSiteUrl(path, raw, problems) {
 /** The origins of a site's pages that may read its published content from the browser. */
 function readCors(path, raw, problems) {
 	if (raw === void 0) return { origins: [] };
-	if (!isRecord$3(raw) || !Array.isArray(raw["origins"])) {
+	if (!isRecord$4(raw) || !Array.isArray(raw["origins"])) {
 		problems.add(path, wrongType(raw, "an object with origins"), "Declare it as { origins: [\"https://example.com\"] }, or remove it.");
 		return { origins: [] };
 	}
@@ -158,7 +158,7 @@ function readBindingName(path, raw, problems) {
 	return null;
 }
 function readWebhook(path, raw, problems) {
-	if (!isRecord$3(raw)) {
+	if (!isRecord$4(raw)) {
 		problems.add(path, wrongType(raw, "a webhook"), "Declare it as { name: \"newsletter\", url: \"https://…\", secret: \"WEBHOOK_SECRET\" }.");
 		return null;
 	}
@@ -183,7 +183,7 @@ function readEvents(path, raw, siteUrl, problems) {
 		indexNow: null
 	};
 	if (raw === void 0) return events;
-	if (!isRecord$3(raw)) {
+	if (!isRecord$4(raw)) {
 		problems.add(path, wrongType(raw, "an object"), "Declare { webhooks: [ … ], indexNow: { … } }.");
 		return events;
 	}
@@ -207,7 +207,7 @@ function readEvents(path, raw, siteUrl, problems) {
 	const indexNow = raw["indexNow"];
 	if (indexNow !== void 0) {
 		const indexPath = keyPath(path, "indexNow");
-		if (!isRecord$3(indexNow)) problems.add(indexPath, wrongType(indexNow, "an object"), "Declare { key: \"<your IndexNow key>\" }.");
+		if (!isRecord$4(indexNow)) problems.add(indexPath, wrongType(indexNow, "an object"), "Declare { key: \"<your IndexNow key>\" }.");
 		else {
 			const raw = indexNow["key"];
 			const key = typeof raw === "string" && INDEXNOW_KEY.test(raw) ? raw : null;
@@ -219,6 +219,39 @@ function readEvents(path, raw, siteUrl, problems) {
 	return events;
 }
 //#endregion
+//#region src/config/audit.ts
+/** The fewest days a site may keep its activity log for, when it sets a retention (ADR-037). */
+const AUDIT_RETENTION_MIN_DAYS = 30;
+/** The most days a retention may be: ten years. Beyond that, keep it with no retention. */
+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. */
+const DEFAULT_AUDIT = {
+	ipAddresses: "off",
+	retentionDays: null
+};
+/** What the activity log of a site keeps, as its owner chose (ADR-037). */
+function readAudit(path, raw, problems) {
+	if (raw === void 0 || raw === null) return DEFAULT_AUDIT;
+	if (!isRecord$4(raw)) {
+		problems.add(path, wrongType(raw, "an object"), "Declare it as { ipAddresses: \"off\", retentionDays: null }, or remove it.");
+		return DEFAULT_AUDIT;
+	}
+	let ipAddresses = "off";
+	const addresses = raw["ipAddresses"];
+	if (addresses === "hashed") ipAddresses = "hashed";
+	else if (addresses !== void 0 && addresses !== "off") problems.add(keyPath(path, "ipAddresses"), wrongType(addresses, "\"off\" or \"hashed\""), "Use \"off\" to keep no address, or \"hashed\" to keep a keyed hash of each.");
+	let retentionDays = null;
+	const days = raw["retentionDays"];
+	if (days !== void 0 && days !== null) {
+		if (typeof days !== "number" || !Number.isInteger(days) || days < 30 || days > 3650) problems.add(keyPath(path, "retentionDays"), `${typeof days === "number" ? String(days) : wrongType(days, "a number")} is not a whole number of days from 30 to ${AUDIT_RETENTION_MAX_DAYS}`, "Give the days to keep each line, or null to keep the log for as long as the site exists.");
+		else retentionDays = days;
+	}
+	return {
+		ipAddresses,
+		retentionDays
+	};
+}
+//#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;
@@ -289,7 +322,7 @@ function runtimeOf(contractId, context) {
 */
 /** The most characters of the entry's own text that a message repeats. */
 const MAX_ECHO_LENGTH = 80;
-function isRecord$2(value) {
+function isRecord$3(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 /** Orders two texts by UTF-16 code units: the same in every runtime, unlike `localeCompare`. */
@@ -342,11 +375,11 @@ function fragmentAt(schema, segments) {
 	let node = schema;
 	for (const segment of segments) {
 		const properties = node.properties;
-		if (isRecord$2(properties) && Object.hasOwn(properties, segment)) {
+		if (isRecord$3(properties) && Object.hasOwn(properties, segment)) {
 			const next = properties[segment];
-			if (!isRecord$2(next)) return void 0;
+			if (!isRecord$3(next)) return void 0;
 			node = next;
-		} else if (/^\d+$/.test(segment) && isRecord$2(node.items)) node = node.items;
+		} else if (/^\d+$/.test(segment) && isRecord$3(node.items)) node = node.items;
 		else return;
 	}
 	return node;
@@ -354,7 +387,7 @@ function fragmentAt(schema, segments) {
 function valueAt(input, segments) {
 	let node = input;
 	for (const segment of segments) if (Array.isArray(node) && /^\d+$/.test(segment)) node = node[Number(segment)];
-	else if (isRecord$2(node) && Object.hasOwn(node, segment)) node = node[segment];
+	else if (isRecord$3(node) && Object.hasOwn(node, segment)) node = node[segment];
 	else return void 0;
 	return node;
 }
@@ -390,11 +423,11 @@ function numberExpectation(type, schema) {
 }
 function arrayExpectation(schema) {
 	const size = range(schema.minItems, schema.maxItems, "item");
-	const items = isRecord$2(schema.items) ? expectation(schema.items) : void 0;
+	const items = isRecord$3(schema.items) ? expectation(schema.items) : void 0;
 	return `an array${size === void 0 ? "" : ` of ${size}`}${items === void 0 ? "" : `, each ${items}`}`;
 }
 function objectExpectation(schema) {
-	const keys = isRecord$2(schema.properties) ? Object.keys(schema.properties) : [];
+	const keys = isRecord$3(schema.properties) ? Object.keys(schema.properties) : [];
 	return keys.length === 0 ? "an object" : `an object with the keys ${keys.join(", ")}`;
 }
 function typeExpectation(type, schema) {
@@ -417,13 +450,13 @@ function expectation(schema) {
 	if ("const" in schema) return `exactly ${JSON.stringify(schema.const)}`;
 	if (Array.isArray(schema.enum)) return `one of ${listValues(schema.enum)}`;
 	const alternatives = schema.anyOf ?? schema.oneOf;
-	const parts = Array.isArray(alternatives) ? alternatives.map((option) => isRecord$2(option) ? expectation(option) : void 0) : (Array.isArray(schema.type) ? schema.type : [schema.type]).map((type) => typeExpectation(type, schema));
+	const parts = Array.isArray(alternatives) ? alternatives.map((option) => isRecord$3(option) ? expectation(option) : void 0) : (Array.isArray(schema.type) ? schema.type : [schema.type]).map((type) => typeExpectation(type, schema));
 	return parts.every((part) => part !== void 0) ? parts.join(" or ") : void 0;
 }
 /** The keys of `value` that an object schema closed to other keys does not list. */
 function unknownKeys(fragment, value) {
 	const { additionalProperties, properties } = fragment;
-	if (additionalProperties !== false || !isRecord$2(properties) || !isRecord$2(value)) return [];
+	if (additionalProperties !== false || !isRecord$3(properties) || !isRecord$3(value)) return [];
 	return Object.keys(value).filter((key) => !Object.hasOwn(properties, key));
 }
 /** The fix for one issue: imperative, naming the field and what the schema accepts there. */
@@ -433,7 +466,7 @@ function fixForIssue({ subject, schema, input, segments, message }) {
 	if (fragment !== void 0) {
 		const unknown = unknownKeys(fragment, valueAt(input, segments));
 		if (unknown.length > 0) {
-			const allowed = isRecord$2(fragment.properties) ? Object.keys(fragment.properties) : [];
+			const allowed = isRecord$3(fragment.properties) ? Object.keys(fragment.properties) : [];
 			const nouns = unknown.length === 1 ? subject.noun : `${subject.noun}s`;
 			const where = allowed.length === 0 ? `no ${subject.noun}s are allowed there` : `the ${subject.noun}s allowed there are: ${allowed.join(", ")}`;
 			return `Remove the ${nouns} ${unknown.map((key) => quote(key)).join(", ")} from ${target}; ${where}.`;
@@ -786,7 +819,7 @@ function chunksOf(entry) {
 //#endregion
 //#region src/contracts/rules.ts
 function present(frontmatter, field) {
-	return isRecord$2(frontmatter) ? frontmatter[field] : void 0;
+	return isRecord$3(frontmatter) ? frontmatter[field] : void 0;
 }
 const GRAPHEMES = new Intl.Segmenter(void 0, { granularity: "grapheme" });
 /** The length of a value as a reader counts it: characters of a text (an emoji is one), items of a list. */
@@ -891,7 +924,7 @@ function bannedWords(params, options = {}) {
 		check: (context) => {
 			if (pattern === null) return [];
 			const findings = [];
-			const frontmatter = isRecord$2(context.frontmatter) ? context.frontmatter : {};
+			const frontmatter = isRecord$3(context.frontmatter) ? context.frontmatter : {};
 			for (const [field, value] of Object.entries(frontmatter)) {
 				if (typeof value !== "string") continue;
 				for (const word of found(value)) findings.push({
@@ -932,7 +965,7 @@ function translationPair(options = {}) {
 			const field = collection.translationGroupField;
 			if (field === null) return [];
 			const path = `/frontmatter${pointer([field])}`;
-			const group = isRecord$2(context.frontmatter) ? context.frontmatter[field] : void 0;
+			const group = isRecord$3(context.frontmatter) ? context.frontmatter[field] : void 0;
 			if (typeof group !== "string" || group === "") return [{
 				path,
 				message: `The entry has no translation group: its frontmatter field ${field} is empty.`,
@@ -1350,7 +1383,7 @@ const TARGET = "draft-2020-12";
 */
 function toJsonSchema$1(schema) {
 	const converted = schema["~standard"].jsonSchema.input({ target: TARGET });
-	if (!isRecord$3(converted)) throw new TypeError(`the library ${wrongType(converted, "a JSON Schema object")}`);
+	if (!isRecord$4(converted)) throw new TypeError(`the library ${wrongType(converted, "a JSON Schema object")}`);
 	return JSON.parse(JSON.stringify(converted));
 }
 /** Reference chains longer than this are cycles. */
@@ -1362,7 +1395,7 @@ function pointTo(root, ref) {
 	let node = root;
 	for (const part of ref.slice(2).split("/")) {
 		const key = part.replaceAll("~1", "/").replaceAll("~0", "~");
-		if (!isRecord$3(node) || !Object.hasOwn(node, key)) return void 0;
+		if (!isRecord$4(node) || !Object.hasOwn(node, key)) return void 0;
 		node = node[key];
 	}
 	return node;
@@ -1374,7 +1407,7 @@ function pointTo(root, ref) {
 function resolveSchema(root, schema) {
 	let node = schema;
 	for (let hop = 0; hop <= MAX_REF_HOPS; hop += 1) {
-		if (!isRecord$3(node)) return null;
+		if (!isRecord$4(node)) return null;
 		const ref = node["$ref"];
 		if (typeof ref !== "string") return node;
 		node = pointTo(root, ref);
@@ -1491,14 +1524,14 @@ function standardProps(value) {
 /** A Standard Schema that also converts to JSON Schema, which is what a collection needs. */
 function isDescribedSchema(value) {
 	const standard = standardProps(value);
-	if (!isRecord$3(standard) || typeof standard["validate"] !== "function") return false;
+	if (!isRecord$4(standard) || typeof standard["validate"] !== "function") return false;
 	const converter = standard["jsonSchema"];
-	return isRecord$3(converter) && typeof converter["input"] === "function";
+	return isRecord$4(converter) && typeof converter["input"] === "function";
 }
 /** What `isDescribedSchema` found missing, for the message. */
 function whyNotDescribed(value) {
 	const standard = standardProps(value);
-	if (!isRecord$3(standard)) return wrongType(value, "a Standard Schema with JSON Schema");
+	if (!isRecord$4(standard)) return wrongType(value, "a Standard Schema with JSON Schema");
 	if (typeof standard["validate"] !== "function") return "has no ~standard.validate function, so it is no Standard Schema";
 	return "has no ~standard.jsonSchema.input function, so describe_site could not show it to agents";
 }
@@ -1568,7 +1601,7 @@ function claimRoute(route, path, site, problems) {
 }
 /** The route of each locale, in the order of the site's locales. */
 function readRoutes(path, raw, collection, site, problems) {
-	if (!isRecord$3(raw)) {
+	if (!isRecord$4(raw)) {
 		problems.add(path, wrongType(raw, "an object with one path per locale"), ROUTES_FIX);
 		return {};
 	}
@@ -1616,7 +1649,7 @@ function readField(path, raw, schema, kind, problems) {
 		return null;
 	}
 	if (schema === null) return raw;
-	const properties = isRecord$3(schema.object["properties"]) ? schema.object["properties"] : {};
+	const properties = isRecord$4(schema.object["properties"]) ? schema.object["properties"] : {};
 	if (!Object.hasOwn(properties, raw)) {
 		const names = Object.keys(properties);
 		problems.add(path, `${quote$1(raw)} is not a property of the schema${names.length === 0 ? ", which declares none" : ` (its properties are ${names.map(quote$1).join(", ")})`}`, `Name a field that the schema declares, or add ${quote$1(raw)} to the schema.`);
@@ -1625,7 +1658,7 @@ function readField(path, raw, schema, kind, problems) {
 }
 function readTranslations(path, raw, schema, problems) {
 	if (raw === void 0) return null;
-	if (!isRecord$3(raw)) {
+	if (!isRecord$4(raw)) {
 		problems.add(path, wrongType(raw, "an object like { groupBy: \"translationGroup\" }"), "Set it to { groupBy: \"<field>\" }, the field of the frontmatter that holds the key the translations of an entry share, or remove it.");
 		return null;
 	}
@@ -1634,7 +1667,7 @@ function readTranslations(path, raw, schema, problems) {
 const COMPONENT_FIX = "Declare it with defineComponent({ props: z.strictObject({ … }) }).";
 function readComponent(path, name, raw, problems) {
 	if (!NAME.test(name)) problems.add(path, `${quote$1(name)} is not a valid component name`, nameFix("callout"));
-	if (!isRecord$3(raw)) {
+	if (!isRecord$4(raw)) {
 		problems.add(path, wrongType(raw, "a component"), COMPONENT_FIX);
 		return null;
 	}
@@ -1652,7 +1685,7 @@ function readComponent(path, name, raw, problems) {
 function readComponents(path, raw, problems) {
 	const components = /* @__PURE__ */ new Map();
 	if (raw === void 0) return components;
-	if (!isRecord$3(raw)) {
+	if (!isRecord$4(raw)) {
 		problems.add(path, wrongType(raw, "an object that maps each component name to its definition"), COMPONENT_FIX);
 		return components;
 	}
@@ -1693,7 +1726,7 @@ function checkPhases(path, raw, problems) {
 * what makes it a `Contract`. Whether it may have its id is a question for `checkIdentity`.
 */
 function isContract(item, path, problems) {
-	if (!isRecord$3(item)) {
+	if (!isRecord$4(item)) {
 		problems.add(path, wrongType(item, "a contract"), "Write it as { id, severity, description, check }.");
 		return false;
 	}
@@ -1741,7 +1774,7 @@ function readContracts(path, raw, problems) {
 		if (isContract(item, itemAt, problems)) {
 			checkIdentity(item.id, isBuiltInContract(item), itemAt, ids, problems);
 			contracts.push(item);
-		} else if (isRecord$3(item) && typeof item["id"] === "string" && CONTRACT_ID.test(item["id"])) checkIdentity(item["id"], false, itemAt, ids, problems);
+		} else if (isRecord$4(item) && typeof item["id"] === "string" && CONTRACT_ID.test(item["id"])) checkIdentity(item["id"], false, itemAt, ids, problems);
 	}
 	return contracts;
 }
@@ -1757,7 +1790,7 @@ function readMaxMarkdownBytes(path, raw, problems) {
 */
 function readCollection(path, name, raw, site, problems) {
 	if (!NAME.test(name)) problems.add(path, `${quote$1(name)} is not a valid collection name`, nameFix("blog"));
-	if (!isRecord$3(raw)) {
+	if (!isRecord$4(raw)) {
 		problems.add(path, wrongType(raw, "a collection"), "Declare it with defineCollection({ schema, routes, … }).");
 		return null;
 	}
@@ -1861,7 +1894,7 @@ function readDefaultLocale(path, raw, locales, problems) {
 const COLLECTIONS_FIX = "Declare at least one: collections: { blog: defineCollection({ schema, routes }) }.";
 function readCollections(path, raw, site, problems) {
 	const collections = /* @__PURE__ */ new Map();
-	if (!isRecord$3(raw)) {
+	if (!isRecord$4(raw)) {
 		problems.add(path, wrongType(raw, "an object that maps each collection name to its collection"), COLLECTIONS_FIX);
 		return collections;
 	}
@@ -1877,7 +1910,7 @@ function readCollections(path, raw, site, problems) {
 function readSite(key, raw, problems) {
 	const path = keyPath("sites", key);
 	if (!isSiteKey(key)) problems.add(path, `${quote$1(key)} is not a valid site key`, SITE_KEY_FIX);
-	if (!isRecord$3(raw)) {
+	if (!isRecord$4(raw)) {
 		problems.add(path, wrongType(raw, "a site"), "Declare it as { locales: [\"en\"], defaultLocale: \"en\", collections: { … } }.");
 		return null;
 	}
@@ -1899,12 +1932,13 @@ function readSite(key, raw, problems) {
 		collections,
 		url,
 		cors: readCors(keyPath(path, "cors"), raw["cors"], problems),
-		events: readEvents(keyPath(path, "events"), raw["events"], url, problems)
+		events: readEvents(keyPath(path, "events"), raw["events"], url, problems),
+		audit: readAudit(keyPath(path, "audit"), raw["audit"], problems)
 	};
 }
 function readSites(raw, problems) {
 	const sites = /* @__PURE__ */ new Map();
-	if (!isRecord$3(raw)) {
+	if (!isRecord$4(raw)) {
 		problems.add("sites", wrongType(raw, "an object that maps the site key to the site"), SITE_FIX);
 		return sites;
 	}
@@ -1919,7 +1953,7 @@ function readSites(raw, problems) {
 /** `auth` of the config: absent, or an object whose `dynamicClientRegistration` is a boolean. */
 function readAuth(raw, problems) {
 	if (raw === void 0) return { dynamicClientRegistration: false };
-	if (!isRecord$3(raw)) {
+	if (!isRecord$4(raw)) {
 		problems.add("auth", wrongType(raw, "an object"), "Write auth: { dynamicClientRegistration: true }, or leave auth out.");
 		return { dynamicClientRegistration: false };
 	}
@@ -1961,7 +1995,7 @@ function resolveConfig(config) {
 	const problems = new Problems();
 	let sites = /* @__PURE__ */ new Map();
 	let auth = { dynamicClientRegistration: false };
-	if (isRecord$3(config)) {
+	if (isRecord$4(config)) {
 		sites = readSites(config["sites"], problems);
 		auth = readAuth(config["auth"], problems);
 	} else problems.add("config", wrongType(config, "an object"), "Export the result of defineConfig({ sites: { … } }) from hollware.config.ts.");
@@ -1972,6 +2006,69 @@ function resolveConfig(config) {
 	};
 }
 //#endregion
+//#region src/audit/index.ts
+/**
+* The actions of the activity log (ADR-037). A line names one of these, and nothing else: a new
+* 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. */
+const OPERATION_AUDIT_ACTIONS = [
+	"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"
+];
+/** What people do outside the operations: their tokens, members, passkeys, sessions and apps. */
+const IDENTITY_AUDIT_ACTIONS = [
+	"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"
+];
+const AUDIT_ACTIONS = [...OPERATION_AUDIT_ACTIONS, ...IDENTITY_AUDIT_ACTIONS];
+/** `denied`: a scope or a role was missing; `failed`: any other error the caller got. */
+const AUDIT_OUTCOMES = [
+	"ok",
+	"denied",
+	"failed"
+];
+/**
+* Who acted: a person in the admin, a personal token, an app a person allowed through OAuth, or
+* the deployment itself (its cron).
+*/
+const AUDIT_ACTOR_KINDS = [
+	"user",
+	"token",
+	"oauth_client",
+	"system"
+];
+function isAuditAction(value) {
+	return AUDIT_ACTIONS.includes(value);
+}
+//#endregion
 //#region src/structure/definition.ts
 /**
 * The definition of a site as data (ADR-033): what D1 stores for it and what the operations that
@@ -2021,6 +2118,13 @@ const siteDefinitionData = z.strictObject({
 		webhooks: [],
 		indexNow: null
 	}),
+	audit: z.strictObject({
+		ipAddresses: z.enum(["off", "hashed"]).default("off").describe("Whether the activity log keeps the address of each request, as a hash keyed by the site, or nothing of it."),
+		retentionDays: z.number().int().min(30).max(AUDIT_RETENTION_MAX_DAYS).nullable().default(null).describe("The days each line of the activity log is kept; null keeps it as long as the site.")
+	}).default({
+		ipAddresses: "off",
+		retentionDays: null
+	}).describe("What the activity log of the site keeps (ADR-037). Only an owner should change it."),
 	collections: z.record(z.string(), collectionDefinitionData)
 });
 //#endregion
@@ -2043,19 +2147,19 @@ const SUMMARIES = /* @__PURE__ */ new Set([
 function segmentsOf$1(location) {
 	return location.replace(/^#\/?/, "").split("/").filter((segment) => segment !== "").map((segment) => decodeURIComponent(segment).replaceAll("~1", "/").replaceAll("~0", "~"));
 }
-function isRecord$1(value) {
+function isRecord$2(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 /** The schema of the object at `segments`, to tell a declared key from an unknown one. */
 function declaredKeys(schema, segments) {
 	let node = schema;
 	for (const segment of segments) {
-		if (!isRecord$1(node)) return /* @__PURE__ */ new Set();
+		if (!isRecord$2(node)) return /* @__PURE__ */ new Set();
 		const properties = node["properties"];
-		node = isRecord$1(properties) && Object.hasOwn(properties, segment) ? properties[segment] : node["items"];
+		node = isRecord$2(properties) && Object.hasOwn(properties, segment) ? properties[segment] : node["items"];
 	}
-	const properties = isRecord$1(node) ? node["properties"] : void 0;
-	return new Set(isRecord$1(properties) ? Object.keys(properties) : []);
+	const properties = isRecord$2(node) ? node["properties"] : void 0;
+	return new Set(isRecord$2(properties) ? Object.keys(properties) : []);
 }
 /** The issues of a validation: one for each part that failed, at the path of the value. */
 function issuesOf(schema, errors) {
@@ -2167,7 +2271,8 @@ function compileSite(path, site, problems) {
 				...webhook.secret === void 0 ? {} : { secret: webhook.secret }
 			})),
 			...site.events.indexNow === null ? {} : { indexNow: site.events.indexNow }
-		}
+		},
+		audit: site.audit
 	};
 }
 /** The definitions of the sites, read from D1 as JSON, checked and resolved. */
@@ -2241,6 +2346,10 @@ function definitionsFromConfig(config) {
 				webhooks: (site.events?.webhooks ?? []).map((webhook) => ({ ...webhook })),
 				indexNow: site.events?.indexNow ?? null
 			},
+			...site.audit === void 0 ? {} : { audit: {
+				ipAddresses: site.audit.ipAddresses ?? "off",
+				retentionDays: site.audit.retentionDays ?? null
+			} },
 			collections: Object.fromEntries(Object.entries(site.collections).map(([name, collection]) => [name, collectionOf(keyPath(keyPath(path, "collections"), name), collection, problems)]))
 		};
 	}
@@ -2388,6 +2497,10 @@ function sitePreset(preset, locales, defaultLocale) {
 			webhooks: [],
 			indexNow: null
 		},
+		audit: {
+			ipAddresses: "off",
+			retentionDays: null
+		},
 		collections
 	};
 }
@@ -2402,6 +2515,7 @@ const ERROR_CODES = [
 	"invalid_input",
 	"unknown_collection",
 	"unknown_locale",
+	"invalid_preview",
 	"insufficient_scope",
 	"output_too_large",
 	"timeout",
@@ -2431,6 +2545,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 = {
+	auditLine: "aud",
 	challenge: "chl",
 	delivery: "dlv",
 	embedding: "emb",
@@ -3533,7 +3648,7 @@ function utf8ByteLength(text) {
 	}
 	return bytes;
 }
-function isRecord(value) {
+function isRecord$1(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function describe(value) {
@@ -3566,8 +3681,8 @@ function linesBeforeBody(source, body) {
 function yamlViolation(error, source) {
 	const reason = Reflect.get(error, "reason");
 	const mark = Reflect.get(error, "mark");
-	const markLine = isRecord(mark) ? mark.line : void 0;
-	const markColumn = isRecord(mark) ? mark.column : void 0;
+	const markLine = isRecord$1(mark) ? mark.line : void 0;
+	const markColumn = isRecord$1(mark) ? mark.column : void 0;
 	const firstLine = source.startsWith("---\r\n") ? 1 : 2;
 	return yamlSyntax(typeof reason === "string" ? reason : error.message.split("\n")[0] ?? "it does not parse", typeof markLine === "number" ? markLine + firstLine : void 0, typeof markColumn === "number" ? markColumn + 1 : void 0);
 }
@@ -3593,7 +3708,7 @@ async function run(markdown, options) {
 		};
 	}
 	const frontmatter = split.data;
-	if (!isRecord(frontmatter)) return {
+	if (!isRecord$1(frontmatter)) return {
 		ok: false,
 		violations: [frontmatterNotMapping(describe(frontmatter))]
 	};
@@ -3700,7 +3815,20 @@ const URL_ATTRIBUTES = /* @__PURE__ */ new Set([
 function isProps(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function sanitizeProps(raw) {
+/** The value a path such as `frontmatter.url` names in the data, or `undefined`. */
+function resolvePath(data, path) {
+	let value = data;
+	for (const part of path.split(".")) {
+		if (typeof value !== "object" || value === null || !Object.hasOwn(value, part)) return void 0;
+		value = Reflect.get(value, part);
+	}
+	return value;
+}
+/** The name of an attribute without the `:` or `v-bind:` of a binding. */
+function unbound(key) {
+	return key.startsWith("v-bind:") ? key.slice(7) : key.replace(/^:/, "");
+}
+function sanitizeProps(raw, data) {
 	const props = {};
 	if (!isProps(raw)) return props;
 	for (const key of Object.keys(raw)) {
@@ -3709,8 +3837,15 @@ function sanitizeProps(raw) {
 		if (isForbiddenAttribute(name)) continue;
 		const value = raw[key];
 		if (URL_ATTRIBUTES.has(name)) {
+			const kind = name === "src" ? "image" : "link";
 			const url = urlValue(key, value);
-			if (url === void 0 || !isSafeUrl(url, name === "src" ? "image" : "link")) continue;
+			if (url === void 0) continue;
+			if (isBinding(key) && url === value) {
+				const bound = resolvePath(data, url);
+				if (typeof bound === "string" && isSafeUrl(bound, kind)) setOwn(props, unbound(key), bound.replaceAll("&", "&amp;"));
+				continue;
+			}
+			if (!isSafeUrl(url, kind)) continue;
 		}
 		setOwn(props, key, typeof value === "string" && !isBinding(key) ? value.replaceAll("&", "&amp;") : value);
 	}
@@ -3722,19 +3857,19 @@ function marker(name) {
 		name: TAG_NAME.test(name) ? shorten(name) : "?"
 	}];
 }
-function sanitizeElement(node, depth) {
+function sanitizeElement(node, depth, data) {
 	const tag = node[0];
 	if (typeof tag !== "string") return void 0;
 	if (!NATIVE_TAGS.has(tag) && tag !== "hollware-marker") {
 		if (!TAG_NAME.test(tag) || DANGEROUS_TAGS.has(tag.toLowerCase())) return marker(tag);
 	}
-	const element = [tag, sanitizeProps(node[1])];
+	const element = [tag, sanitizeProps(node[1], data)];
 	if (depth >= 100) return element;
 	for (let at = 2; at < node.length; at++) {
 		const child = node[at];
 		if (typeof child === "string") element.push(child);
 		else if (Array.isArray(child)) {
-			const clean = sanitizeElement(child, depth + 1);
+			const clean = sanitizeElement(child, depth + 1, data);
 			if (clean !== void 0) element.push(clean);
 		}
 	}
@@ -3743,10 +3878,14 @@ function sanitizeElement(node, depth) {
 /** Copies a document through the rules of this file. */
 function sanitizeDocument(document) {
 	const nodes = [];
+	const data = {
+		frontmatter: document.frontmatter,
+		meta: document.meta
+	};
 	if (Array.isArray(document.nodes)) {
 		for (const node of document.nodes) if (typeof node === "string") nodes.push(node);
 		else if (Array.isArray(node)) {
-			const clean = sanitizeElement(node, 1);
+			const clean = sanitizeElement(node, 1, data);
 			if (clean !== void 0) nodes.push(clean);
 		}
 	}
@@ -4681,13 +4820,13 @@ 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();
+const encoder$1 = new TextEncoder();
 async function hmac(secret, text) {
-	const key = await crypto.subtle.importKey("raw", encoder.encode(secret), {
+	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.encode(text)))].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+	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) {
@@ -4700,9 +4839,20 @@ function sameText(a, b) {
 	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.
+* 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);
@@ -4710,7 +4860,139 @@ async function verifyWebhook(check) {
 	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;
-	return sameText(signature, await signWebhook(check.secret, timestamp, check.body));
+	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
+* latest revision of one entry, for one hour. A site that reads published content only (the
+* binding of RPC, the read API) reads that entry's head instead when it presents one.
+*
+*   hw_prv_<payload>.<signature>
+*
+* The payload is base64url of `{ "s": site, "e": entryId, "x": expiresAtSeconds }`, and the
+* signature the base64url HMAC-SHA256 of the payload text under a key that HKDF-SHA256 derives
+* from the Worker secret `HOLLWARE_SECRET`, bound to the site. Nothing is stored: a token cannot
+* be revoked, only wait out its hour, and rotating the secret ends every one.
+*/
+const PREVIEW_TOKEN_PREFIX = "hw_prv_";
+/** The query parameter a site's page takes the token from. */
+const PREVIEW_QUERY_PARAM = "hollware-preview";
+/** How long a token lasts, in seconds. */
+const PREVIEW_TTL_SECONDS = 3600;
+/** The least characters of `HOLLWARE_SECRET` that Hollware signs anything with. */
+const PREVIEW_SECRET_MIN_LENGTH = 32;
+/** Whether a Worker's secret can sign previews: present and long enough. */
+function canSignPreviews(secret) {
+	return secret !== void 0 && secret.length >= 32;
+}
+const encoder = new TextEncoder();
+function toBase64Url(bytes) {
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+function fromBase64Url(text) {
+	if (!/^[A-Za-z0-9_-]*$/.test(text)) return null;
+	try {
+		const binary = atob(text.replaceAll("-", "+").replaceAll("_", "/"));
+		return Uint8Array.from(binary, (char) => char.charCodeAt(0));
+	} catch {
+		return null;
+	}
+}
+async function previewKey(secret, site) {
+	const base = await crypto.subtle.importKey("raw", encoder.encode(secret), "HKDF", false, ["deriveKey"]);
+	return crypto.subtle.deriveKey({
+		name: "HKDF",
+		hash: "SHA-256",
+		salt: /* @__PURE__ */ new Uint8Array(0),
+		info: encoder.encode(`hollware preview\n${site}`)
+	}, base, {
+		name: "HMAC",
+		hash: "SHA-256",
+		length: 256
+	}, false, ["sign", "verify"]);
+}
+/** A token for one entry of one site, valid for `PREVIEW_TTL_SECONDS` from `now`. */
+async function makePreviewToken(input) {
+	if (!canSignPreviews(input.secret)) throw new Error(`HOLLWARE_SECRET must be at least 32 characters.`);
+	const expires = Math.floor(input.now.getTime() / 1e3) + PREVIEW_TTL_SECONDS;
+	const payload = toBase64Url(encoder.encode(JSON.stringify({
+		s: input.site,
+		e: input.entryId,
+		x: expires
+	})));
+	const mac = await crypto.subtle.sign("HMAC", await previewKey(input.secret, input.site), encoder.encode(payload));
+	return {
+		token: `${PREVIEW_TOKEN_PREFIX}${payload}.${toBase64Url(new Uint8Array(mac))}`,
+		expiresAt: (/* @__PURE__ */ new Date(expires * 1e3)).toISOString()
+	};
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Checks a token for a site. The signature is verified (in constant time, by `crypto.subtle`)
+* before the payload is parsed, under the key of the site that is asked: a token made for another
+* site fails there. The entry the token names is the caller's to compare with the entry it read.
+*/
+async function verifyPreviewToken(input) {
+	if (!canSignPreviews(input.secret)) return {
+		ok: false,
+		reason: "no_secret"
+	};
+	const { token } = input;
+	if (!token.startsWith("hw_prv_")) return {
+		ok: false,
+		reason: "malformed"
+	};
+	const parts = token.slice(7).split(".");
+	const [payload, signature] = parts;
+	if (parts.length !== 2 || payload === void 0 || signature === void 0) return {
+		ok: false,
+		reason: "malformed"
+	};
+	const mac = fromBase64Url(signature);
+	const body = fromBase64Url(payload);
+	if (mac === null || body === null) return {
+		ok: false,
+		reason: "malformed"
+	};
+	if (!await crypto.subtle.verify("HMAC", await previewKey(input.secret, input.site), mac, encoder.encode(payload))) return {
+		ok: false,
+		reason: "signature"
+	};
+	let claims;
+	try {
+		claims = JSON.parse(new TextDecoder().decode(body));
+	} catch {
+		return {
+			ok: false,
+			reason: "malformed"
+		};
+	}
+	if (!isRecord(claims) || typeof claims["s"] !== "string" || typeof claims["e"] !== "string" || typeof claims["x"] !== "number") return {
+		ok: false,
+		reason: "malformed"
+	};
+	if (claims["s"] !== input.site) return {
+		ok: false,
+		reason: "site"
+	};
+	if (Math.floor(input.now.getTime() / 1e3) >= claims["x"]) return {
+		ok: false,
+		reason: "expired"
+	};
+	return {
+		ok: true,
+		entryId: claims["e"],
+		expiresAt: (/* @__PURE__ */ new Date(claims["x"] * 1e3)).toISOString()
+	};
 }
 //#endregion
 //#region src/events.ts
@@ -4835,4 +5117,4 @@ function tagsOfSiteChange(collections, locales) {
 //#region src/index.ts
 const name = "@hollware/core";
 //#endregion
-export { BUILT_IN_CONTRACT_IDS, CATALOG, CHUNKER_VERSION, CHUNK_LIMITS, COMARK_VERSION, ConfigError, DEFAULT_MAX_MARKDOWN_BYTES, ERROR_CODES, EVENT_ID_HEADER, EVERY_LOCALE, HollwareError, ID_PREFIXES, INDEXNOW_KEY, MAX_MARKDOWN_BYTES_CEILING, OPERATIONS, PERSONAL_TOKEN_PREFIX, PERSONAL_TOKEN_TTL_DAYS, PIPELINE_VERSION, PRESETS, READ_TOKEN_PREFIX, REFUSAL_CONTRACT_IDS, SCOPES, SIGNATURE_HEADER, SITE_KEY_MAX_LENGTH, SITE_KEY_PATTERN, SITE_TAG, TIMESTAMP_HEADER, approveReview, 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, isBuiltInContract, isId, isPersonalToken, isReadToken, isScope, isSiteKey, listEntries, listReviews, listTag, 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, verifyWebhook, webhookDefinition };
+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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hollware/core",
-  "version": "0.10.0",
+  "version": "1.0.0-rc.0",
   "description": "Contracts, operation specs, schemas and the Markdown pipeline of Hollware. No Cloudflare dependencies.",
   "homepage": "https://hollware.com",
   "bugs": {
@@ -16,6 +16,7 @@
     "dist"
   ],
   "type": "module",
+  "sideEffects": false,
   "exports": {
     ".": {
       "types": "./dist/index.d.mts",