@hollware/core 0.2.0 → 0.4.0

package/dist/index.d.mts

@@ -290,6 +290,13 @@ interface SiteDefinition {
   readonly styleGuide?: string;
   /** The public origin of the site, such as `https://example.com`: entries' URLs start with it. */
   readonly url?: string;
+  /**
+   * The origins whose pages may read the published content of the site from the browser, over
+   * the read API with a read token (`hw_read_`). None by default.
+   */
+  readonly cors?: {
+    readonly origins: readonly string[];
+  };
   /** Who hears about publications (ADR-025). */
   readonly events?: {
     /** Each gets every event, signed with HMAC-SHA256 by the Worker secret named in `secret`. */
@@ -311,6 +318,17 @@ interface HollwareConfig {
    * content exists. v0.1 serves exactly one site per deployment.
    */
   readonly sites: Readonly<Record<string, SiteDefinition>>;
+  /** How MCP clients and the admin get tokens (ADR-026). */
+  readonly auth?: AuthDefinition;
+}
+/** The OAuth server of a deployment. */
+interface AuthDefinition {
+  /**
+   * Whether a client may register itself (RFC 7591), for MCP clients that cannot present a
+   * Client ID Metadata Document. Off by default: a registration is a write to KV that anyone can
+   * make, and MCP 2026-07-28 prefers metadata documents.
+   */
+  readonly dynamicClientRegistration?: boolean;
 }
 /** A collection once the config is resolved: checked, with every default filled in. */
 interface ResolvedCollection {
@@ -335,6 +353,10 @@ interface ResolvedSite {
   readonly collections: ReadonlyMap<string, ResolvedCollection>;
   /** The public origin of the site, or `null`. */
   readonly url: string | null;
+  /** The origins that may call the read API from a page, each as `URL.origin` gives it. */
+  readonly cors: {
+    readonly origins: readonly string[];
+  };
   readonly events: ResolvedEvents;
 }
 /** A webhook of a site; `secret` names the Worker secret that signs its deliveries. */
@@ -350,9 +372,14 @@ interface ResolvedEvents {
     readonly key: string;
   } | null;
 }
-/** The config once resolved, at the start of the Worker. v0.1 holds exactly one site. */
+/** The config once resolved, at the start of the Worker: one site or more (ADR-027). */
 interface ResolvedConfig {
   readonly sites: ReadonlyMap<string, ResolvedSite>;
+  readonly auth: ResolvedAuth;
+}
+/** The OAuth server once the config is resolved. */
+interface ResolvedAuth {
+  readonly dynamicClientRegistration: boolean;
 }
 /**
  * Checks a config and fills in its defaults. It throws one error that lists every problem, each
@@ -412,7 +439,7 @@ export declare const DEFAULT_MAX_MARKDOWN_BYTES = 524288;
  */
 export declare const MAX_MARKDOWN_BYTES_CEILING = 786432;
 declare namespace schemas_d_exports {
-  export { acknowledgedWarning, collectionDescription, collectionName, componentDescription, conflict, contractDescription, document, entry, entryId, entryStatus, entrySummary, format, locale, markdown, phase, publication, revisionId, severity, siteDescription, slug, verdict, version, violation };
+  export { acknowledgedWarning, collectionDescription, collectionName, componentDescription, conflict, contractDescription, document, entry, entryId, entryStatus, entrySummary, format, locale, markdown, phase, publication, review, reviewId, reviewStatus, revisionId, severity, siteDescription, slug, verdict, version, violation };
 }
 /**
  * The pieces the operation schemas share. Their descriptions become the JSON Schema that agents
@@ -639,6 +666,34 @@ declare const entry: z.ZodObject<{
   }, z.core.$strip>>;
   html: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+declare const reviewId: z.ZodString;
+declare const reviewStatus: z.ZodEnum<{
+  approved: "approved";
+  cancelled: "cancelled";
+  changes_requested: "changes_requested";
+  pending: "pending";
+}>;
+/**
+ * A request to publish a revision, made by someone who may write but not publish, and what a
+ * person who may publish decided about it.
+ */
+declare const review: z.ZodObject<{
+  id: z.ZodString;
+  entryId: z.ZodString;
+  revision: z.ZodString;
+  status: z.ZodEnum<{
+    approved: "approved";
+    cancelled: "cancelled";
+    changes_requested: "changes_requested";
+    pending: "pending";
+  }>;
+  requestedBy: z.ZodString;
+  requestedByName: z.ZodNullable<z.ZodString>;
+  requestedAt: z.ZodString;
+  decidedBy: z.ZodNullable<z.ZodString>;
+  decidedAt: z.ZodNullable<z.ZodString>;
+  note: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
 declare const conflict: z.ZodObject<{
   currentVersion: z.ZodNumber;
   headRevision: z.ZodString;
@@ -910,7 +965,7 @@ export declare function describeResolvedSite(site: ResolvedSite, options?: {
 /**
  * Checks the config of the deployment and fills in its defaults, or throws a `ConfigError` with
  * every problem it found, so that a broken `hollware.config.ts` stops the Worker at startup with
- * a message that says what to change. v0.1 serves exactly one site per deployment.
+ * a message that says what to change. A deployment serves one site or more.
  *
  * The parameter is `unknown` because the config comes from user code that may be plain
  * JavaScript; a `HollwareConfig` is accepted as is, so this is a `ResolveConfig`. Notes on the
@@ -991,13 +1046,19 @@ 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 challenge: 'chl';
   readonly delivery: 'dlv';
   readonly entry: 'ent';
   readonly event: 'evt';
+  readonly invitation: 'inv';
+  readonly member: 'mbr';
+  readonly passkey: 'pky';
   readonly publication: 'pub';
   readonly revision: 'rev';
   readonly revisionTag: 'tag';
+  readonly review: 'rvw';
   readonly schedule: 'sch';
+  readonly session: 'ses';
   readonly token: 'tok';
   readonly user: 'usr';
 };
@@ -1186,6 +1247,7 @@ export declare const getEntry: OperationSpec<"get_entry", z.ZodObject<{
     html: "html";
     markdown: "markdown";
   }>>>;
+  published: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strict>, z.ZodObject<{
   outcome: z.ZodEnum<{
     not_found: "not_found";
@@ -1495,6 +1557,7 @@ export declare const publish: OperationSpec<"publish", z.ZodObject<{
     conflict: "conflict";
     needs_acknowledgement: "needs_acknowledgement";
     not_found: "not_found";
+    pending_review: "pending_review";
     published: "published";
     scheduled: "scheduled";
   }>;
@@ -1550,6 +1613,23 @@ export declare const publish: OperationSpec<"publish", z.ZodObject<{
     currentVersion: z.ZodNumber;
     headRevision: z.ZodString;
   }, z.core.$strip>>;
+  review: z.ZodOptional<z.ZodObject<{
+    id: z.ZodString;
+    entryId: z.ZodString;
+    revision: z.ZodString;
+    status: z.ZodEnum<{
+      approved: "approved";
+      cancelled: "cancelled";
+      changes_requested: "changes_requested";
+      pending: "pending";
+    }>;
+    requestedBy: z.ZodString;
+    requestedByName: z.ZodNullable<z.ZodString>;
+    requestedAt: z.ZodString;
+    decidedBy: z.ZodNullable<z.ZodString>;
+    decidedAt: z.ZodNullable<z.ZodString>;
+    note: z.ZodNullable<z.ZodString>;
+  }, z.core.$strip>>;
   failedEntry: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>>;
 export declare const unpublish: OperationSpec<"unpublish", z.ZodObject<{
@@ -1578,8 +1658,242 @@ export declare const unpublish: OperationSpec<"unpublish", z.ZodObject<{
     updatedAt: z.ZodString;
   }, z.core.$strip>>;
 }, z.core.$strip>>;
-/** Every operation of v0.1, sorted by name: the order of `tools/list`. */
-export declare const OPERATIONS: readonly [OperationSpec<"create_draft", z.ZodObject<{
+export declare const listReviews: OperationSpec<"list_reviews", z.ZodObject<{
+  status: z.ZodDefault<z.ZodEnum<{
+    approved: "approved";
+    cancelled: "cancelled";
+    changes_requested: "changes_requested";
+    pending: "pending";
+  }>>;
+  limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+  outcome: z.ZodEnum<{
+    ok: "ok";
+  }>;
+  reviews: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    entryId: z.ZodString;
+    revision: z.ZodString;
+    status: z.ZodEnum<{
+      approved: "approved";
+      cancelled: "cancelled";
+      changes_requested: "changes_requested";
+      pending: "pending";
+    }>;
+    requestedBy: z.ZodString;
+    requestedByName: z.ZodNullable<z.ZodString>;
+    requestedAt: z.ZodString;
+    decidedBy: z.ZodNullable<z.ZodString>;
+    decidedAt: z.ZodNullable<z.ZodString>;
+    note: z.ZodNullable<z.ZodString>;
+    entry: z.ZodObject<{
+      id: z.ZodString;
+      collection: z.ZodString;
+      locale: z.ZodString;
+      slug: z.ZodString;
+      translationGroup: z.ZodNullable<z.ZodString>;
+      status: z.ZodEnum<{
+        draft: "draft";
+        published: "published";
+        scheduled: "scheduled";
+      }>;
+      version: z.ZodNumber;
+      frontmatter: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+      tags: z.ZodArray<z.ZodString>;
+      hasUnpublishedChanges: z.ZodBoolean;
+      publishedAt: z.ZodNullable<z.ZodString>;
+      updatedAt: z.ZodString;
+    }, z.core.$strip>;
+  }, z.core.$strip>>;
+}, z.core.$strip>>;
+export declare const approveReview: OperationSpec<"approve_review", z.ZodObject<{
+  id: z.ZodString;
+  acknowledgeWarnings: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    contract: z.ZodString;
+    path: z.ZodString;
+  }, z.core.$strip>>>;
+}, z.core.$strict>, z.ZodObject<{
+  outcome: z.ZodEnum<{
+    blocked: "blocked";
+    needs_acknowledgement: "needs_acknowledgement";
+    not_found: "not_found";
+    not_pending: "not_pending";
+    published: "published";
+  }>;
+  review: z.ZodOptional<z.ZodObject<{
+    id: z.ZodString;
+    entryId: z.ZodString;
+    revision: z.ZodString;
+    status: z.ZodEnum<{
+      approved: "approved";
+      cancelled: "cancelled";
+      changes_requested: "changes_requested";
+      pending: "pending";
+    }>;
+    requestedBy: z.ZodString;
+    requestedByName: z.ZodNullable<z.ZodString>;
+    requestedAt: z.ZodString;
+    decidedBy: z.ZodNullable<z.ZodString>;
+    decidedAt: z.ZodNullable<z.ZodString>;
+    note: z.ZodNullable<z.ZodString>;
+  }, z.core.$strip>>;
+  entry: z.ZodOptional<z.ZodObject<{
+    id: z.ZodString;
+    collection: z.ZodString;
+    locale: z.ZodString;
+    slug: z.ZodString;
+    translationGroup: z.ZodNullable<z.ZodString>;
+    status: z.ZodEnum<{
+      draft: "draft";
+      published: "published";
+      scheduled: "scheduled";
+    }>;
+    version: z.ZodNumber;
+    frontmatter: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    tags: z.ZodArray<z.ZodString>;
+    hasUnpublishedChanges: z.ZodBoolean;
+    publishedAt: z.ZodNullable<z.ZodString>;
+    updatedAt: z.ZodString;
+  }, z.core.$strip>>;
+  verdict: z.ZodOptional<z.ZodObject<{
+    ok: z.ZodBoolean;
+    phase: z.ZodEnum<{
+      publish: "publish";
+      write: "write";
+    }>;
+    errors: z.ZodArray<z.ZodObject<{
+      contract: z.ZodString;
+      severity: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+      }>;
+      path: z.ZodString;
+      message: z.ZodString;
+      fix: z.ZodString;
+      line: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    warnings: z.ZodArray<z.ZodObject<{
+      contract: z.ZodString;
+      severity: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+      }>;
+      path: z.ZodString;
+      message: z.ZodString;
+      fix: z.ZodString;
+      line: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    contractsHash: z.ZodString;
+  }, z.core.$strip>>;
+}, z.core.$strip>>;
+export declare const requestChanges: OperationSpec<"request_changes", z.ZodObject<{
+  id: z.ZodString;
+  note: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+  outcome: z.ZodEnum<{
+    changes_requested: "changes_requested";
+    not_found: "not_found";
+    not_pending: "not_pending";
+  }>;
+  review: z.ZodOptional<z.ZodObject<{
+    id: z.ZodString;
+    entryId: z.ZodString;
+    revision: z.ZodString;
+    status: z.ZodEnum<{
+      approved: "approved";
+      cancelled: "cancelled";
+      changes_requested: "changes_requested";
+      pending: "pending";
+    }>;
+    requestedBy: z.ZodString;
+    requestedByName: z.ZodNullable<z.ZodString>;
+    requestedAt: z.ZodString;
+    decidedBy: z.ZodNullable<z.ZodString>;
+    decidedAt: z.ZodNullable<z.ZodString>;
+    note: z.ZodNullable<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;
+  acknowledgeWarnings: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    contract: z.ZodString;
+    path: z.ZodString;
+  }, z.core.$strip>>>;
+}, z.core.$strict>, z.ZodObject<{
+  outcome: z.ZodEnum<{
+    blocked: "blocked";
+    needs_acknowledgement: "needs_acknowledgement";
+    not_found: "not_found";
+    not_pending: "not_pending";
+    published: "published";
+  }>;
+  review: z.ZodOptional<z.ZodObject<{
+    id: z.ZodString;
+    entryId: z.ZodString;
+    revision: z.ZodString;
+    status: z.ZodEnum<{
+      approved: "approved";
+      cancelled: "cancelled";
+      changes_requested: "changes_requested";
+      pending: "pending";
+    }>;
+    requestedBy: z.ZodString;
+    requestedByName: z.ZodNullable<z.ZodString>;
+    requestedAt: z.ZodString;
+    decidedBy: z.ZodNullable<z.ZodString>;
+    decidedAt: z.ZodNullable<z.ZodString>;
+    note: z.ZodNullable<z.ZodString>;
+  }, z.core.$strip>>;
+  entry: z.ZodOptional<z.ZodObject<{
+    id: z.ZodString;
+    collection: z.ZodString;
+    locale: z.ZodString;
+    slug: z.ZodString;
+    translationGroup: z.ZodNullable<z.ZodString>;
+    status: z.ZodEnum<{
+      draft: "draft";
+      published: "published";
+      scheduled: "scheduled";
+    }>;
+    version: z.ZodNumber;
+    frontmatter: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    tags: z.ZodArray<z.ZodString>;
+    hasUnpublishedChanges: z.ZodBoolean;
+    publishedAt: z.ZodNullable<z.ZodString>;
+    updatedAt: z.ZodString;
+  }, z.core.$strip>>;
+  verdict: z.ZodOptional<z.ZodObject<{
+    ok: z.ZodBoolean;
+    phase: z.ZodEnum<{
+      publish: "publish";
+      write: "write";
+    }>;
+    errors: z.ZodArray<z.ZodObject<{
+      contract: z.ZodString;
+      severity: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+      }>;
+      path: z.ZodString;
+      message: z.ZodString;
+      fix: z.ZodString;
+      line: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    warnings: z.ZodArray<z.ZodObject<{
+      contract: z.ZodString;
+      severity: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+      }>;
+      path: z.ZodString;
+      message: z.ZodString;
+      fix: z.ZodString;
+      line: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    contractsHash: z.ZodString;
+  }, z.core.$strip>>;
+}, z.core.$strip>>, OperationSpec<"create_draft", z.ZodObject<{
   collection: z.ZodString;
   locale: z.ZodString;
   slug: z.ZodString;
@@ -1684,6 +1998,7 @@ export declare const OPERATIONS: readonly [OperationSpec<"create_draft", z.ZodOb
     html: "html";
     markdown: "markdown";
   }>>>;
+  published: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strict>, z.ZodObject<{
   outcome: z.ZodEnum<{
     not_found: "not_found";
@@ -1843,6 +2158,53 @@ export declare const OPERATIONS: readonly [OperationSpec<"create_draft", z.ZodOb
     updatedAt: z.ZodString;
   }, z.core.$strip>>;
   nextCursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>>, OperationSpec<"list_reviews", z.ZodObject<{
+  status: z.ZodDefault<z.ZodEnum<{
+    approved: "approved";
+    cancelled: "cancelled";
+    changes_requested: "changes_requested";
+    pending: "pending";
+  }>>;
+  limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+  outcome: z.ZodEnum<{
+    ok: "ok";
+  }>;
+  reviews: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    entryId: z.ZodString;
+    revision: z.ZodString;
+    status: z.ZodEnum<{
+      approved: "approved";
+      cancelled: "cancelled";
+      changes_requested: "changes_requested";
+      pending: "pending";
+    }>;
+    requestedBy: z.ZodString;
+    requestedByName: z.ZodNullable<z.ZodString>;
+    requestedAt: z.ZodString;
+    decidedBy: z.ZodNullable<z.ZodString>;
+    decidedAt: z.ZodNullable<z.ZodString>;
+    note: z.ZodNullable<z.ZodString>;
+    entry: z.ZodObject<{
+      id: z.ZodString;
+      collection: z.ZodString;
+      locale: z.ZodString;
+      slug: z.ZodString;
+      translationGroup: z.ZodNullable<z.ZodString>;
+      status: z.ZodEnum<{
+        draft: "draft";
+        published: "published";
+        scheduled: "scheduled";
+      }>;
+      version: z.ZodNumber;
+      frontmatter: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+      tags: z.ZodArray<z.ZodString>;
+      hasUnpublishedChanges: z.ZodBoolean;
+      publishedAt: z.ZodNullable<z.ZodString>;
+      updatedAt: z.ZodString;
+    }, z.core.$strip>;
+  }, z.core.$strip>>;
 }, z.core.$strip>>, OperationSpec<"publish", z.ZodObject<{
   id: z.ZodString;
   version: z.ZodNumber;
@@ -1861,6 +2223,7 @@ export declare const OPERATIONS: readonly [OperationSpec<"create_draft", z.ZodOb
     conflict: "conflict";
     needs_acknowledgement: "needs_acknowledgement";
     not_found: "not_found";
+    pending_review: "pending_review";
     published: "published";
     scheduled: "scheduled";
   }>;
@@ -1916,7 +2279,50 @@ export declare const OPERATIONS: readonly [OperationSpec<"create_draft", z.ZodOb
     currentVersion: z.ZodNumber;
     headRevision: z.ZodString;
   }, z.core.$strip>>;
+  review: z.ZodOptional<z.ZodObject<{
+    id: z.ZodString;
+    entryId: z.ZodString;
+    revision: z.ZodString;
+    status: z.ZodEnum<{
+      approved: "approved";
+      cancelled: "cancelled";
+      changes_requested: "changes_requested";
+      pending: "pending";
+    }>;
+    requestedBy: z.ZodString;
+    requestedByName: z.ZodNullable<z.ZodString>;
+    requestedAt: z.ZodString;
+    decidedBy: z.ZodNullable<z.ZodString>;
+    decidedAt: z.ZodNullable<z.ZodString>;
+    note: z.ZodNullable<z.ZodString>;
+  }, z.core.$strip>>;
   failedEntry: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>, OperationSpec<"request_changes", z.ZodObject<{
+  id: z.ZodString;
+  note: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+  outcome: z.ZodEnum<{
+    changes_requested: "changes_requested";
+    not_found: "not_found";
+    not_pending: "not_pending";
+  }>;
+  review: z.ZodOptional<z.ZodObject<{
+    id: z.ZodString;
+    entryId: z.ZodString;
+    revision: z.ZodString;
+    status: z.ZodEnum<{
+      approved: "approved";
+      cancelled: "cancelled";
+      changes_requested: "changes_requested";
+      pending: "pending";
+    }>;
+    requestedBy: z.ZodString;
+    requestedByName: z.ZodNullable<z.ZodString>;
+    requestedAt: z.ZodString;
+    decidedBy: z.ZodNullable<z.ZodString>;
+    decidedAt: z.ZodNullable<z.ZodString>;
+    note: z.ZodNullable<z.ZodString>;
+  }, z.core.$strip>>;
 }, z.core.$strip>>, OperationSpec<"unpublish", z.ZodObject<{
   id: z.ZodString;
 }, z.core.$strict>, z.ZodObject<{
@@ -2061,6 +2467,11 @@ type OperationByName<Name extends OperationName> = Extract<Operation, {
  * row of a token has an id of its own (`tok_…`, see `ids.ts`), its scopes and its expiry.
  */
 export declare const PERSONAL_TOKEN_PREFIX = "hw_pat_";
+/**
+ * Read tokens: `hw_read_` and the same 52 characters. A read token reads the published content of
+ * one site over the read API (`GET /v1/…`) and nothing else, so a site may ship one to a browser.
+ */
+export declare const READ_TOKEN_PREFIX = "hw_read_";
 /** Days until a new personal token expires, unless whoever creates it asks for another expiry. */
 export declare const PERSONAL_TOKEN_TTL_DAYS = 90;
 /**
@@ -2069,8 +2480,12 @@ export declare const PERSONAL_TOKEN_TTL_DAYS = 90;
  * tests pass their own bytes.
  */
 export declare function generatePersonalToken(random?: Uint8Array): string;
+/** A new read token, made as a personal token is. */
+export declare function generateReadToken(random?: Uint8Array): string;
 /** Whether a string has the shape of a personal token. It says nothing about whether one exists. */
 export declare function isPersonalToken(value: string): boolean;
+/** Whether a string has the shape of a read token. It says nothing about whether one exists. */
+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
@@ -2104,4 +2519,4 @@ export declare function verifyWebhook(check: WebhookCheck): Promise<boolean>;
 //#region src/index.d.ts
 export declare const name = "@hollware/core";
 //#endregion
-export { type AcknowledgedWarning, type BuiltInContractId, type BuiltInOptions, type CollectionDefinition, 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 EntryFacts, type EntryLookup, type EntryRef, type ErrorCode, type ExtractedContent, type Heading, type HollwareConfig, type IdPrefix, type ImageRef, type LinkRef, type LinkTarget, type Operation, type OperationByName, type OperationName, type OperationSpec, type OutcomeInfo, type OutcomeOf, type Phase, type ProcessMarkdown, type ProcessMarkdownOptions, type ProcessResult, type ProcessedMarkdown, type RenderHtml, type ResolveConfig, type ResolvedCollection, type ResolvedConfig, type ResolvedSite, type RunContractsInput, type SchemaOutput, type Scope, type Severity, type SiteDefinition, type SiteDescription, type Verdict, type Violation, schemas_d_exports as schemas };
+export { type AcknowledgedWarning, type AuthDefinition, type BuiltInContractId, type BuiltInOptions, type CollectionDefinition, 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 EntryFacts, type EntryLookup, type EntryRef, type ErrorCode, type ExtractedContent, type Heading, type HollwareConfig, type IdPrefix, type ImageRef, type LinkRef, type LinkTarget, type Operation, type OperationByName, type OperationName, type OperationSpec, type OutcomeInfo, type OutcomeOf, type Phase, type ProcessMarkdown, type ProcessMarkdownOptions, type ProcessResult, type ProcessedMarkdown, type RenderHtml, type ResolveConfig, type ResolvedAuth, type ResolvedCollection, type ResolvedConfig, type ResolvedSite, type RunContractsInput, type SchemaOutput, type Scope, type Severity, type SiteDefinition, type SiteDescription, type Verdict, type Violation, schemas_d_exports as schemas };

package/dist/index.mjs

@@ -1396,6 +1396,20 @@ function readSiteUrl(path, raw, problems) {
 	}
 	return url.origin;
 }
+/** 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$1(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: [] };
+	}
+	const origins = [];
+	for (const [index, origin] of raw["origins"].entries()) {
+		const read = readSiteUrl(itemPath(keyPath(path, "origins"), index), origin, problems);
+		if (read !== null && !origins.includes(read)) origins.push(read);
+	}
+	return { origins };
+}
 function readBindingName(path, raw, problems) {
 	if (typeof raw === "string" && BINDING_NAME.test(raw)) return raw;
 	problems.add(path, wrongType(raw, "the name of a Worker secret"), "Name the secret that holds the value, such as \"WEBHOOK_SECRET\", and set it with wrangler secret put.");
@@ -1573,6 +1587,7 @@ function readSite(key, raw, problems) {
 		styleGuide,
 		collections,
 		url,
+		cors: readCors(keyPath(path, "cors"), raw["cors"], problems),
 		events: readEvents(keyPath(path, "events"), raw["events"], url, problems)
 	};
 }
@@ -1583,18 +1598,32 @@ function readSites(raw, problems) {
 		return sites;
 	}
 	const keys = Object.keys(raw);
-	if (keys.length === 0) problems.add("sites", "has no site, and v0.1 serves exactly one site per deployment", SITE_FIX);
-	else if (keys.length > 1) problems.add("sites", `has ${keys.length} sites (${keys.map(quote).join(", ")}), and v0.1 serves exactly one site per deployment`, "Keep exactly one site in sites.");
+	if (keys.length === 0) problems.add("sites", "has no site, and a deployment serves at least one", SITE_FIX);
 	for (const key of keys) {
 		const site = readSite(key, raw[key], problems);
 		if (site !== null) sites.set(key, site);
 	}
 	return sites;
 }
+/** `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$1(raw)) {
+		problems.add("auth", wrongType(raw, "an object"), "Write auth: { dynamicClientRegistration: true }, or leave auth out.");
+		return { dynamicClientRegistration: false };
+	}
+	const value = raw["dynamicClientRegistration"];
+	if (value === void 0) return { dynamicClientRegistration: false };
+	if (typeof value !== "boolean") {
+		problems.add("auth.dynamicClientRegistration", wrongType(value, "true or false"), "Write true to let MCP clients register themselves, or leave it out.");
+		return { dynamicClientRegistration: false };
+	}
+	return { dynamicClientRegistration: value };
+}
 /**
 * Checks the config of the deployment and fills in its defaults, or throws a `ConfigError` with
 * every problem it found, so that a broken `hollware.config.ts` stops the Worker at startup with
-* a message that says what to change. v0.1 serves exactly one site per deployment.
+* a message that says what to change. A deployment serves one site or more.
 *
 * The parameter is `unknown` because the config comes from user code that may be plain
 * JavaScript; a `HollwareConfig` is accepted as is, so this is a `ResolveConfig`. Notes on the
@@ -1620,10 +1649,16 @@ function readSites(raw, problems) {
 function resolveConfig(config) {
 	const problems = new Problems();
 	let sites = /* @__PURE__ */ new Map();
-	if (isRecord$1(config)) sites = readSites(config["sites"], problems);
-	else problems.add("config", wrongType(config, "an object"), "Export the result of defineConfig({ sites: { … } }) from hollware.config.ts.");
+	let auth = { dynamicClientRegistration: false };
+	if (isRecord$1(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.");
 	if (problems.list.length > 0) throw new ConfigError(problems.list);
-	return { sites };
+	return {
+		sites,
+		auth
+	};
 }
 //#endregion
 //#region src/errors.ts
@@ -1665,13 +1700,19 @@ 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 = {
+	challenge: "chl",
 	delivery: "dlv",
 	entry: "ent",
 	event: "evt",
+	invitation: "inv",
+	member: "mbr",
+	passkey: "pky",
 	publication: "pub",
 	revision: "rev",
 	revisionTag: "tag",
+	review: "rvw",
 	schedule: "sch",
+	session: "ses",
 	token: "tok",
 	user: "usr"
 };
@@ -3007,6 +3048,9 @@ var schemas_exports = /* @__PURE__ */ __exportAll({
 	markdown: () => markdown,
 	phase: () => phase,
 	publication: () => publication,
+	review: () => review,
+	reviewId: () => reviewId,
+	reviewStatus: () => reviewStatus,
 	revisionId: () => revisionId,
 	severity: () => severity,
 	siteDescription: () => siteDescription,
@@ -3086,6 +3130,29 @@ const entry = entrySummary.extend({
 	document: document.optional(),
 	html: z.string().optional()
 });
+const reviewId = z.string().regex(/^rvw_[0-9A-HJKMNP-TV-Z]{26}$/).describe("The id of a review (rvw_…), as publish and list_reviews return it.");
+const reviewStatus = z.enum([
+	"pending",
+	"approved",
+	"changes_requested",
+	"cancelled"
+]);
+/**
+* A request to publish a revision, made by someone who may write but not publish, and what a
+* person who may publish decided about it.
+*/
+const review = z.object({
+	id: reviewId,
+	entryId,
+	revision: revisionId.describe("The revision asked for."),
+	status: reviewStatus.describe("pending until someone decides; cancelled when a new revision of the entry is saved."),
+	requestedBy: z.string().describe("The user who asked."),
+	requestedByName: z.string().nullable().describe("The name of the user who asked, if they gave one."),
+	requestedAt: z.string(),
+	decidedBy: z.string().nullable(),
+	decidedAt: z.string().nullable(),
+	note: z.string().nullable().describe("What the reviewer asked to change, or null.")
+});
 const conflict = z.object({
 	currentVersion: z.number().int().min(1),
 	headRevision: revisionId
@@ -3181,7 +3248,8 @@ const getEntry = defineOperation({
 		collection: collectionName,
 		locale,
 		slug,
-		formats: z.array(format).min(1).default(["markdown"]).describe("What to return of the revision: markdown, the Comark document, or html.")
+		formats: z.array(format).min(1).default(["markdown"]).describe("What to return of the revision: markdown, the Comark document, or html."),
+		published: z.boolean().default(false).describe("Read the revision that is live instead of the latest one: not_found when the entry is not published.")
 	}),
 	output: z.object({
 		outcome: z.enum(["ok", "not_found"]),
@@ -3287,7 +3355,7 @@ const validate = defineOperation({
 const publish = defineOperation({
 	name: "publish",
 	title: "Publish an entry",
-	description: "Publishes the latest revision of an entry, if the entry is still at the version you read, and with group, other entries in the same step. It is blocked while the contracts report errors. Warnings have to be acknowledged: an answer of needs_acknowledgement lists them, and publish again with them in acknowledgeWarnings. Publish entries that link to each other as one group.",
+	description: "Publishes the latest revision of an entry, if the entry is still at the version you read, and with group, other entries in the same step. It is blocked while the contracts report errors. Warnings have to be acknowledged: an answer of needs_acknowledgement lists them, and publish again with them in acknowledgeWarnings. Publish entries that link to each other as one group. Without content:publish, the same checks run and the answer is pending_review: a person who may publish approves the revision or asks for changes, and a new revision of the entry cancels the request. A review is for one entry, now: never with group or publishAt.",
 	input: z.strictObject({
 		id: entryId,
 		version,
@@ -3304,21 +3372,24 @@ const publish = defineOperation({
 			"scheduled",
 			"blocked",
 			"needs_acknowledgement",
+			"pending_review",
 			"conflict",
 			"not_found"
 		]),
 		entry: entrySummary.optional(),
 		verdict: verdict.optional(),
 		conflict: conflict.optional(),
-		failedEntry: entryId.optional().describe("In a group, the entry that kept the group from being published.")
+		review: review.optional().describe("With pending_review: the request, as list_reviews shows it."),
+		failedEntry: entryId.optional().describe("In a group, the entry that kept the group from being published: blocked, stale, missing, or with a warning to acknowledge.")
 	}),
-	scopes: ["content:publish"],
+	scopes: ["content:write"],
 	effect: "write",
 	outcomes: {
 		published: { isError: false },
 		scheduled: { isError: false },
 		blocked: { isError: true },
 		needs_acknowledgement: { isError: false },
+		pending_review: { isError: false },
 		conflict: { isError: true },
 		not_found: { isError: true }
 	}
@@ -3339,14 +3410,87 @@ const unpublish = defineOperation({
 		not_found: { isError: true }
 	}
 });
-/** Every operation of v0.1, sorted by name: the order of `tools/list`. */
+const listReviews = defineOperation({
+	name: "list_reviews",
+	title: "List the reviews",
+	description: "Lists the requests to publish, newest first, with the entry each one is for: the pending ones unless you name another status.",
+	input: z.strictObject({
+		status: reviewStatus.default("pending"),
+		limit: z.number().int().min(1).max(100).default(50)
+	}),
+	output: z.object({
+		outcome: z.enum(["ok"]),
+		reviews: z.array(review.extend({ entry: entrySummary }))
+	}),
+	scopes: ["content:read"],
+	effect: "read",
+	outcomes: { ok: { isError: false } }
+});
+const approveReview = defineOperation({
+	name: "approve_review",
+	title: "Approve a review",
+	description: "Publishes the revision a review asked for, in your name, after the contracts run again as publish runs them. The warnings the request acknowledged count as acknowledged; a new one answers needs_acknowledgement, and you approve again with it in acknowledgeWarnings.",
+	input: z.strictObject({
+		id: reviewId,
+		acknowledgeWarnings: z.array(acknowledgedWarning).default([]).describe("Warnings you accept besides those the request acknowledged.")
+	}),
+	output: z.object({
+		outcome: z.enum([
+			"published",
+			"blocked",
+			"needs_acknowledgement",
+			"not_pending",
+			"not_found"
+		]),
+		review: review.optional(),
+		entry: entrySummary.optional(),
+		verdict: verdict.optional()
+	}),
+	scopes: ["content:publish"],
+	effect: "write",
+	outcomes: {
+		published: { isError: false },
+		blocked: { isError: true },
+		needs_acknowledgement: { isError: false },
+		not_pending: { isError: true },
+		not_found: { isError: true }
+	}
+});
+const requestChanges = defineOperation({
+	name: "request_changes",
+	title: "Ask for changes",
+	description: "Closes a pending review without publishing, with a note that says what to change. The author saves a new revision and asks again.",
+	input: z.strictObject({
+		id: reviewId,
+		note: z.string().trim().min(1).max(4e3).describe("What to change, for the author.")
+	}),
+	output: z.object({
+		outcome: z.enum([
+			"changes_requested",
+			"not_pending",
+			"not_found"
+		]),
+		review: review.optional()
+	}),
+	scopes: ["content:publish"],
+	effect: "edit",
+	outcomes: {
+		changes_requested: { isError: false },
+		not_pending: { isError: true },
+		not_found: { isError: true }
+	}
+});
+/** Every operation, sorted by name: the order of `tools/list`. */
 const OPERATIONS = [
+	approveReview,
 	createDraft,
 	describeSite,
 	getEntry,
 	getTranslations,
 	listEntries,
+	listReviews,
 	publish,
+	requestChanges,
 	unpublish,
 	updateDraft,
 	validate
@@ -3376,26 +3520,43 @@ function isScope(value) {
 * row of a token has an id of its own (`tok_…`, see `ids.ts`), its scopes and its expiry.
 */
 const PERSONAL_TOKEN_PREFIX = "hw_pat_";
+/**
+* Read tokens: `hw_read_` and the same 52 characters. A read token reads the published content of
+* one site over the read API (`GET /v1/…`) and nothing else, so a site may ship one to a browser.
+*/
+const READ_TOKEN_PREFIX = "hw_read_";
 /** Days until a new personal token expires, unless whoever creates it asks for another expiry. */
 const PERSONAL_TOKEN_TTL_DAYS = 90;
 const ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz";
 const SECRET_LENGTH = 52;
 const TOKEN_PATTERN = /^hw_pat_[0-9a-hjkmnp-tv-z]{52}$/;
+const READ_TOKEN_PATTERN = /^hw_read_[0-9a-hjkmnp-tv-z]{52}$/;
 /**
 * A new personal token. Each of the 52 random bytes gives one character (its low 5 bits, which
 * are uniform because 256 is a multiple of 32). `random` defaults to `crypto.getRandomValues`;
 * tests pass their own bytes.
 */
 function generatePersonalToken(random = crypto.getRandomValues(new Uint8Array(SECRET_LENGTH))) {
-	if (random.length !== SECRET_LENGTH) throw new RangeError(`a personal token takes ${SECRET_LENGTH} random bytes, got ${random.length}`);
+	return PERSONAL_TOKEN_PREFIX + secretOf(random, "a personal token");
+}
+/** A new read token, made as a personal token is. */
+function generateReadToken(random = crypto.getRandomValues(new Uint8Array(SECRET_LENGTH))) {
+	return READ_TOKEN_PREFIX + secretOf(random, "a read token");
+}
+function secretOf(random, what) {
+	if (random.length !== SECRET_LENGTH) throw new RangeError(`${what} takes ${SECRET_LENGTH} random bytes, got ${random.length}`);
 	let secret = "";
 	for (const byte of random) secret += ALPHABET.charAt(byte & 31);
-	return PERSONAL_TOKEN_PREFIX + secret;
+	return secret;
 }
 /** Whether a string has the shape of a personal token. It says nothing about whether one exists. */
 function isPersonalToken(value) {
 	return TOKEN_PATTERN.test(value);
 }
+/** Whether a string has the shape of a read token. It says nothing about whether one exists. */
+function isReadToken(value) {
+	return READ_TOKEN_PATTERN.test(value);
+}
 /** The SHA-256 of a token, in lowercase hex: what the `tokens` table stores and looks up. */
 async function hashPersonalToken(token) {
 	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(token));
@@ -3449,4 +3610,4 @@ async function verifyWebhook(check) {
 //#region src/index.ts
 const name = "@hollware/core";
 //#endregion
-export { BUILT_IN_CONTRACT_IDS, COMARK_VERSION, ConfigError, DEFAULT_MAX_MARKDOWN_BYTES, ERROR_CODES, EVENT_ID_HEADER, HollwareError, ID_PREFIXES, MAX_MARKDOWN_BYTES_CEILING, OPERATIONS, PERSONAL_TOKEN_PREFIX, PERSONAL_TOKEN_TTL_DAYS, PIPELINE_VERSION, REFUSAL_CONTRACT_IDS, SCOPES, SIGNATURE_HEADER, SITE_KEY_MAX_LENGTH, SITE_KEY_PATTERN, TIMESTAMP_HEADER, contracts, createDraft, defineCollection, defineComponent, defineConfig, defineContract, defineOperation, describeBuiltInContracts, describeContract, describeResolvedSite, describeSite, generatePersonalToken, getEntry, getTranslations, hashPersonalToken, isBuiltInContract, isId, isPersonalToken, isScope, isSiteKey, listEntries, name, newId, processMarkdown, publish, renderHtml, resolveConfig, runContracts, schemas_exports as schemas, signWebhook, sizeLimitViolation, ulid, uniqueSlugViolation, uniqueTranslationViolation, unpublish, updateDraft, validate, verifyWebhook };
+export { BUILT_IN_CONTRACT_IDS, COMARK_VERSION, ConfigError, DEFAULT_MAX_MARKDOWN_BYTES, ERROR_CODES, EVENT_ID_HEADER, HollwareError, ID_PREFIXES, MAX_MARKDOWN_BYTES_CEILING, OPERATIONS, PERSONAL_TOKEN_PREFIX, PERSONAL_TOKEN_TTL_DAYS, PIPELINE_VERSION, READ_TOKEN_PREFIX, REFUSAL_CONTRACT_IDS, SCOPES, SIGNATURE_HEADER, SITE_KEY_MAX_LENGTH, SITE_KEY_PATTERN, TIMESTAMP_HEADER, approveReview, contracts, createDraft, defineCollection, defineComponent, defineConfig, defineContract, defineOperation, describeBuiltInContracts, describeContract, describeResolvedSite, describeSite, generatePersonalToken, generateReadToken, getEntry, getTranslations, hashPersonalToken, isBuiltInContract, isId, isPersonalToken, isReadToken, isScope, isSiteKey, listEntries, listReviews, name, newId, processMarkdown, publish, renderHtml, requestChanges, resolveConfig, runContracts, schemas_exports as schemas, signWebhook, sizeLimitViolation, ulid, uniqueSlugViolation, uniqueTranslationViolation, unpublish, updateDraft, validate, verifyWebhook };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hollware/core",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Contracts, operation specs, schemas and the Markdown pipeline of Hollware. No Cloudflare dependencies.",
   "homepage": "https://hollware.com",
   "bugs": {