@hollware/core 0.3.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`. */
@@ -346,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. */
@@ -361,7 +372,7 @@ 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;
@@ -954,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
@@ -2456,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;
 /**
@@ -2464,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

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,8 +1598,7 @@ 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);
@@ -1609,7 +1623,7 @@ function readAuth(raw, problems) {
 /**
 * 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
@@ -3506,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));
@@ -3579,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, approveReview, contracts, createDraft, defineCollection, defineComponent, defineConfig, defineContract, defineOperation, describeBuiltInContracts, describeContract, describeResolvedSite, describeSite, generatePersonalToken, getEntry, getTranslations, hashPersonalToken, isBuiltInContract, isId, isPersonalToken, 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 };
+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.3.0",
+  "version": "0.4.0",
   "description": "Contracts, operation specs, schemas and the Markdown pipeline of Hollware. No Cloudflare dependencies.",
   "homepage": "https://hollware.com",
   "bugs": {