@hollware/server 0.3.0 → 0.5.0

package/dist/{ceremonies-D7tsWU3S.mjs → ceremonies-BM9G03lZ.mjs}

@@ -1,4 +1,4 @@
-import { a as findInvitation, c as invitationById, d as saveChallenge, f as takeChallenge, i as createUser, l as passkeysOf, m as userHandle, o as findPasskey, p as touchPasskey, r as createSession, t as addPasskey, u as redeemInvitation } from "./store-Sq0pwUQv.mjs";
+import { a as findInvitation, c as invitationById, d as redeemInvitation, f as saveChallenge, h as userHandle, i as createUser, m as touchPasskey, o as findPasskey, p as takeChallenge, r as createSession, t as addPasskey, u as passkeysOf } from "./store-DiS8UFI2.mjs";
 import { HollwareError, newId } from "@hollware/core";
 import { generateAuthenticationOptions, generateRegistrationOptions, verifyAuthenticationResponse, verifyRegistrationResponse } from "@simplewebauthn/server";
 import { isoBase64URL } from "@simplewebauthn/server/helpers";
@@ -17,10 +17,10 @@ function refused(message, fix) {
 }
 /** The options of `navigator.credentials.create` for the person of an invitation. */
 async function registrationOptions(ceremony, invitationSecret) {
-	const invitation = await findInvitation(ceremony.db, ceremony.site, invitationSecret, ceremony.now);
+	const invitation = await findInvitation(ceremony.db, invitationSecret, ceremony.now);
 	if (invitation === null) throw refused("This link is not valid: it was used already, or it expired.", "Ask the owner of this Hollware for a new invitation.");
 	const userId = invitation.userId ?? newId("usr");
-	const existing = invitation.userId === null ? [] : await passkeysOf(ceremony.db, ceremony.site, invitation.userId);
+	const existing = invitation.userId === null ? [] : await passkeysOf(ceremony.db, invitation.userId);
 	const rp = relyingParty(ceremony);
 	const options = await generateRegistrationOptions({
 		rpName: "Hollware",
@@ -36,7 +36,6 @@ async function registrationOptions(ceremony, invitationSecret) {
 	});
 	return {
 		challengeId: await saveChallenge(ceremony.db, {
-			site: ceremony.site,
 			challenge: options.challenge,
 			purpose: "register",
 			invitationId: invitation.id,
@@ -52,7 +51,6 @@ async function registrationOptions(ceremony, invitationSecret) {
 */
 async function verifyRegistration(ceremony, input) {
 	const challenge = await takeChallenge(ceremony.db, {
-		site: ceremony.site,
 		id: input.challengeId,
 		purpose: "register",
 		now: ceremony.now
@@ -66,18 +64,17 @@ async function verifyRegistration(ceremony, input) {
 		expectedRPID: rp.id
 	});
 	if (!verified.verified) throw refused("The passkey could not be verified.", "Try again.");
-	const invitation = await invitationById(ceremony.db, ceremony.site, challenge.invitationId);
-	if (invitation === null || !await redeemInvitation(ceremony.db, ceremony.site, invitation.id, ceremony.now)) throw refused("This link is not valid: it was used already, or it expired.", "Ask the owner of this Hollware for a new invitation.");
+	const invitation = await invitationById(ceremony.db, challenge.invitationId);
+	if (invitation === null || !await redeemInvitation(ceremony.db, invitation.id, ceremony.now)) throw refused("This link is not valid: it was used already, or it expired.", "Ask the owner of this Hollware for a new invitation.");
 	if (invitation.userId === null) await createUser(ceremony.db, {
 		id: challenge.userId,
 		name: input.name.trim() === "" ? "Unnamed" : input.name.trim(),
 		role: invitation.role,
-		site: ceremony.site,
+		site: invitation.site,
 		now: ceremony.now
 	});
 	const { credential } = verified.registrationInfo;
 	await addPasskey(ceremony.db, {
-		site: ceremony.site,
 		userId: challenge.userId,
 		credentialId: credential.id,
 		publicKey: isoBase64URL.fromBuffer(credential.publicKey),
@@ -87,7 +84,6 @@ async function verifyRegistration(ceremony, input) {
 		now: ceremony.now
 	});
 	const session = await createSession(ceremony.db, {
-		site: ceremony.site,
 		userId: challenge.userId,
 		now: ceremony.now,
 		hours: SESSION_HOURS
@@ -97,7 +93,7 @@ async function verifyRegistration(ceremony, input) {
 		session: session.secret
 	};
 }
-/** The options of `navigator.credentials.get`: any passkey of this site, chosen by the person. */
+/** The options of `navigator.credentials.get`: any passkey of this deployment, chosen by the person. */
 async function authenticationOptions(ceremony) {
 	const rp = relyingParty(ceremony);
 	const options = await generateAuthenticationOptions({
@@ -106,7 +102,6 @@ async function authenticationOptions(ceremony) {
 	});
 	return {
 		challengeId: await saveChallenge(ceremony.db, {
-			site: ceremony.site,
 			challenge: options.challenge,
 			purpose: "authenticate",
 			invitationId: null,
@@ -116,16 +111,15 @@ async function authenticationOptions(ceremony) {
 		options
 	};
 }
-/** Verifies a sign-in with a passkey of this site, and opens the person's session. */
+/** Verifies a sign-in with a passkey of this deployment, and opens the person's session. */
 async function verifyAuthentication(ceremony, input) {
 	const challenge = await takeChallenge(ceremony.db, {
-		site: ceremony.site,
 		id: input.challengeId,
 		purpose: "authenticate",
 		now: ceremony.now
 	});
 	if (challenge === null) throw refused("The sign-in expired.", "Sign in again.");
-	const passkey = await findPasskey(ceremony.db, ceremony.site, input.response.id);
+	const passkey = await findPasskey(ceremony.db, input.response.id);
 	if (passkey === null) throw refused("This passkey is not one of this Hollware.", "Use a passkey you registered here.");
 	const rp = relyingParty(ceremony);
 	const verified = await verifyAuthenticationResponse({
@@ -143,7 +137,6 @@ async function verifyAuthentication(ceremony, input) {
 	if (!verified.verified) throw refused("The passkey could not be verified.", "Try again.");
 	await touchPasskey(ceremony.db, passkey.id, verified.authenticationInfo.newCounter, ceremony.now);
 	const session = await createSession(ceremony.db, {
-		site: ceremony.site,
 		userId: passkey.userId,
 		now: ceremony.now,
 		hours: SESSION_HOURS

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { AcknowledgedWarning, EntryDocument, EntryLookup, EntryRef, HollwareConfig, OperationByName, OperationName, ResolvedSite, Scope, Verdict, describeSite, getEntry, getTranslations, listEntries } from "@hollware/core";
+import { AcknowledgedWarning, EntryDocument, EntryLookup, EntryRef, HollwareConfig, OperationByName, OperationName, ResolvedSite, Scope, Verdict, describeSite, getEntry, getTranslations, listEntries, search } from "@hollware/core";
 import * as z from "zod";
 import { WorkerEntrypoint } from "cloudflare:workers";
 //#region src/ports.d.ts
@@ -102,6 +102,27 @@ interface ListQuery {
   /** The `nextCursor` of the previous page. */
   readonly cursor?: string;
 }
+/** A full-text search of the published entries of a site. */
+interface SearchQuery {
+  /** What the person or the agent typed: its words are matched, its punctuation is not. */
+  readonly text: string;
+  readonly collection?: string;
+  readonly locale?: string;
+  readonly limit: number;
+}
+/** An entry that a search found, best first. */
+interface SearchHit {
+  readonly entry: EntrySummaryView;
+  /** The words around the match in the text, the match between `[` and `]`. */
+  readonly snippet: string;
+  /** How well it matches: higher is better. */
+  readonly score: number;
+}
+/** An entry close to another by meaning, and how close: higher is closer. */
+interface RelatedEntry {
+  readonly id: string;
+  readonly score: number;
+}
 /** The answer to a write that the store could not make. */
 type WriteRefusal = {
   readonly outcome: 'conflict';
@@ -179,6 +200,15 @@ interface ContentStore {
     readonly entries: readonly EntrySummaryView[];
     readonly nextCursor: string | null;
   }>;
+  /**
+   * The published entries whose title, tags or text hold every word of the query, best first:
+   * the title weighs most, then the tags, then the text (bm25).
+   */
+  searchEntries(site: string, query: SearchQuery): Promise<readonly SearchHit[]>;
+  /** The entries of those ids that the view has, in the order of the ids. */
+  findSummaries(site: string, ids: readonly string[], view: View): Promise<readonly EntrySummaryView[]>;
+  /** The entries closest to one by meaning, closest first (ADR-030); `[]` when it has no vectors. */
+  relatedOf(site: string, entryId: string): Promise<readonly RelatedEntry[]>;
   /** The entries of a translation group, one per locale, in the given view. */
   listTranslations(site: string, collection: string, translationGroup: string, view: View): Promise<readonly EntrySummaryView[]>;
   /** What cross-entry contracts read, scoped to the site. */
@@ -290,6 +320,83 @@ interface ContentStore {
 interface Clock {
   now(): Date;
 }
+/** Turns texts into vectors, all of the same length. */
+interface Embedder {
+  /** The model, which the stored vectors name: another model makes them stale. */
+  readonly model: string;
+  embed(texts: readonly string[]): Promise<number[][]>;
+}
+/** What a vector says about where it comes from, to filter and to read a match back. */
+interface VectorMetadata {
+  readonly site: string;
+  readonly entry: string;
+  readonly collection: string;
+  readonly locale: string;
+  /** The piece of the entry: 0 for its summary. */
+  readonly piece: number;
+  /** The start of the piece's text, for the snippet of a match. */
+  readonly excerpt: string;
+}
+interface StoredVector {
+  /** `<entry id>:<piece>`. */
+  readonly id: string;
+  readonly values: readonly number[];
+  readonly metadata: VectorMetadata;
+}
+interface VectorMatch {
+  readonly id: string;
+  /** How close: higher is closer. */
+  readonly score: number;
+  readonly metadata: VectorMetadata;
+}
+interface VectorIndex {
+  upsert(vectors: readonly StoredVector[]): Promise<void>;
+  remove(ids: readonly string[]): Promise<void>;
+  /** The stored values of those vectors; an id the index does not have is left out. */
+  get(ids: readonly string[]): Promise<readonly {
+    readonly id: string;
+    readonly values: readonly number[];
+  }[]>;
+  /** The `topK` vectors nearest to `values` among those of the site, narrowed as asked. */
+  query(values: readonly number[], options: {
+    readonly topK: number;
+    readonly site: string;
+    readonly collection?: string;
+    readonly locale?: string;
+    /** Only the summaries, one vector per entry. */
+    readonly summariesOnly?: boolean;
+  }): Promise<readonly VectorMatch[]>;
+}
+/** What semantic search needs: both services, or the deployment has none. */
+interface Semantic {
+  readonly embedder: Embedder;
+  readonly index: VectorIndex;
+}
+/** A page view, as a site's beacon reports it. */
+interface PageView {
+  readonly site: string;
+  /** The path of the page, such as `/blog/edge-caching/`. */
+  readonly path: string;
+  /** The two letters of the reader's country, or `XX` when it is not known. */
+  readonly country: string;
+}
+/** Where page views are counted. */
+interface AnalyticsWriter {
+  record(view: PageView): void;
+}
+/** A page and how often it was read. */
+interface PageCount {
+  readonly path: string;
+  readonly views: number;
+}
+/** Reads the counts back. */
+interface AnalyticsReader {
+  /** The `limit` most read paths of the site in the last `days`, most read first. */
+  topPages(site: string, query: {
+    readonly days: number;
+    readonly limit: number;
+  }): Promise<readonly PageCount[]>;
+}
 //#endregion
 //#region src/events/run.d.ts
 /** A message of the events Queue: the site and the id of an outbox row. */
@@ -333,6 +440,17 @@ type Principal = {
   readonly site: string;
   /** The scopes of the grant intersected with those of the user's role, as of now. */
   readonly scopes: readonly Scope[];
+} | {
+  /**
+   * A read token (`hw_read_`): it reads the published content of its site over the read API,
+   * and the gateway turns it away from every other route.
+   */
+  readonly kind: 'read';
+  readonly userId: string;
+  readonly tokenId: string;
+  readonly site: string;
+  /** `content:read` while its user's role has it, else nothing. */
+  readonly scopes: readonly Scope[];
 } | {
   /** A Worker of the same account, over the RPC binding: it reads published content. */
   readonly kind: 'binding';
@@ -360,6 +478,10 @@ interface OperationContext {
    * the Queue now rather than at the next sweep of the cron trigger (ADR-025). Absent in tests.
    */
   readonly notify?: (eventIds: readonly string[]) => void;
+  /** The model and the vector index, when the Worker has both (ADR-030); absent or `null` without. */
+  readonly semantic?: Semantic | null;
+  /** The counts of page views, when the deployment can read them (ADR-031); absent or `null` without. */
+  readonly analytics?: AnalyticsReader | null;
 }
 /** The handler of one operation: its parsed input in, its output out. */
 type OperationHandler<Name extends OperationName> = (input: z.output<OperationByName<Name>['input']>, context: OperationContext) => Promise<z.output<OperationByName<Name>['output']>>;
@@ -407,6 +529,24 @@ export interface HollwareEnv {
   readonly ASSETS?: Fetcher;
   /** The Queue of publication events (ADR-025); without it, the cron trigger delivers them. */
   readonly EVENTS?: EventQueue;
+  /**
+   * Workers AI and a Vectorize index (v0.5): with both, every published entry is embedded and
+   * `search` can be semantic; without either, search is full text only.
+   */
+  readonly AI?: Ai;
+  /** `wrangler types` names a Vectorize binding `VectorizeIndex`; either works. */
+  readonly VECTORIZE?: Vectorize | VectorizeIndex;
+  /** The embedding model of Workers AI, `@cf/baai/bge-m3` when not set; its index must match it. */
+  readonly HOLLWARE_EMBEDDING_MODEL?: string;
+  /**
+   * Analytics (ADR-031): the Analytics Engine dataset that the beacon of the sites writes to, and
+   * what `content_stats` reads it with: the account, an API token with Account Analytics Read
+   * (a secret), and the dataset's name when it is not `hollware_page_views`.
+   */
+  readonly ANALYTICS?: AnalyticsEngineDataset;
+  readonly HOLLWARE_ANALYTICS_ACCOUNT_ID?: string;
+  readonly HOLLWARE_ANALYTICS_TOKEN?: string;
+  readonly HOLLWARE_ANALYTICS_DATASET?: string;
 }
 type Output<Spec extends {
   output: z.ZodType;
@@ -418,6 +558,8 @@ type Output<Spec extends {
 export interface HollwareRpc {
   getEntry(site: string, collection: string, slug: string, locale: string, options?: {
     readonly formats?: readonly ('markdown' | 'document' | 'html')[];
+    /** Also the published entries closest by meaning (ADR-030). */
+    readonly related?: boolean;
   }): Promise<Output<typeof getEntry>>;
   listEntries(site: string, collection: string, options?: {
     readonly locale?: string;
@@ -427,6 +569,13 @@ export interface HollwareRpc {
   }): Promise<Output<typeof listEntries>>;
   getTranslations(site: string, collection: string, translationGroup: string): Promise<Output<typeof getTranslations>>;
   describeSite(site: string): Promise<Output<typeof describeSite>>;
+  /** The published entries that match `query`, best first: by its words, by meaning, or both. */
+  search(site: string, query: string, options?: {
+    readonly collection?: string;
+    readonly locale?: string;
+    readonly limit?: number;
+    readonly mode?: 'fulltext' | 'semantic' | 'hybrid';
+  }): Promise<Output<typeof search>>;
 }
 /**
  * What `createHollware(config)` returns. The user's Worker is
@@ -453,4 +602,4 @@ export type CreateHollware = (config: HollwareConfig) => HollwareWorker;
  */
 export declare const createHollware: CreateHollware;
 //#endregion
-export type { Actor, Clock, ContentStore, EntrySummaryView, EntryView, EventMessage, Handlers, ListQuery, NewRevision, OperationContext, OperationHandler, OutboxEvent, Principal, PublishWrite, ReviewStatus, RevisionSummary, StoredEntry, StoredPublication, StoredReview, StoredRevision, StoredSchedule, View, WriteRefusal };
+export type { Actor, AnalyticsReader, AnalyticsWriter, Clock, ContentStore, Embedder, EntrySummaryView, EntryView, EventMessage, Handlers, ListQuery, NewRevision, OperationContext, OperationHandler, OutboxEvent, PageCount, PageView, Principal, PublishWrite, RelatedEntry, ReviewStatus, RevisionSummary, SearchHit, SearchQuery, Semantic, StoredEntry, StoredPublication, StoredReview, StoredRevision, StoredSchedule, StoredVector, VectorIndex, VectorMatch, VectorMetadata, View, WriteRefusal };