@hollware/server 0.1.0 → 0.3.0

package/dist/ceremonies-D7tsWU3S.mjs

@@ -0,0 +1,157 @@
+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 { HollwareError, newId } from "@hollware/core";
+import { generateAuthenticationOptions, generateRegistrationOptions, verifyAuthenticationResponse, verifyRegistrationResponse } from "@simplewebauthn/server";
+import { isoBase64URL } from "@simplewebauthn/server/helpers";
+//#region src/identity/ceremonies.ts
+/** How long a session lasts: a working day. */
+const SESSION_HOURS = 12;
+function relyingParty(ceremony) {
+	const url = new URL(ceremony.publicUrl);
+	return {
+		id: url.hostname,
+		origin: url.origin
+	};
+}
+function refused(message, fix) {
+	return new HollwareError("invalid_input", 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);
+	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 rp = relyingParty(ceremony);
+	const options = await generateRegistrationOptions({
+		rpName: "Hollware",
+		rpID: rp.id,
+		userName: userId,
+		userID: userHandle(userId),
+		attestationType: "none",
+		excludeCredentials: existing.map((passkey) => ({ id: passkey.credentialId })),
+		authenticatorSelection: {
+			residentKey: "required",
+			userVerification: "preferred"
+		}
+	});
+	return {
+		challengeId: await saveChallenge(ceremony.db, {
+			site: ceremony.site,
+			challenge: options.challenge,
+			purpose: "register",
+			invitationId: invitation.id,
+			userId,
+			now: ceremony.now
+		}),
+		options
+	};
+}
+/**
+* Verifies a registration and redeems its invitation, once: a new person is made with the
+* invitation's role, or the passkey joins the person the link names. Opens their session.
+*/
+async function verifyRegistration(ceremony, input) {
+	const challenge = await takeChallenge(ceremony.db, {
+		site: ceremony.site,
+		id: input.challengeId,
+		purpose: "register",
+		now: ceremony.now
+	});
+	if (challenge === null || challenge.invitationId === null || challenge.userId === null) throw refused("The registration expired.", "Start again from the link.");
+	const rp = relyingParty(ceremony);
+	const verified = await verifyRegistrationResponse({
+		response: input.response,
+		expectedChallenge: challenge.challenge,
+		expectedOrigin: rp.origin,
+		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.");
+	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,
+		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),
+		counter: credential.counter,
+		transports: credential.transports ?? [],
+		label: input.label.trim() === "" ? "Passkey" : input.label.trim(),
+		now: ceremony.now
+	});
+	const session = await createSession(ceremony.db, {
+		site: ceremony.site,
+		userId: challenge.userId,
+		now: ceremony.now,
+		hours: SESSION_HOURS
+	});
+	return {
+		userId: challenge.userId,
+		session: session.secret
+	};
+}
+/** The options of `navigator.credentials.get`: any passkey of this site, chosen by the person. */
+async function authenticationOptions(ceremony) {
+	const rp = relyingParty(ceremony);
+	const options = await generateAuthenticationOptions({
+		rpID: rp.id,
+		userVerification: "preferred"
+	});
+	return {
+		challengeId: await saveChallenge(ceremony.db, {
+			site: ceremony.site,
+			challenge: options.challenge,
+			purpose: "authenticate",
+			invitationId: null,
+			userId: null,
+			now: ceremony.now
+		}),
+		options
+	};
+}
+/** Verifies a sign-in with a passkey of this site, 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);
+	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({
+		response: input.response,
+		expectedChallenge: challenge.challenge,
+		expectedOrigin: rp.origin,
+		expectedRPID: rp.id,
+		credential: {
+			id: passkey.credentialId,
+			publicKey: isoBase64URL.toBuffer(passkey.publicKey),
+			counter: passkey.counter,
+			transports: JSON.parse(passkey.transports)
+		}
+	});
+	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
+	});
+	return {
+		userId: passkey.userId,
+		session: session.secret
+	};
+}
+//#endregion
+export { authenticationOptions, registrationOptions, verifyAuthentication, verifyRegistration };

package/dist/index.d.mts

@@ -1,26 +1,6 @@
 import { AcknowledgedWarning, EntryDocument, EntryLookup, EntryRef, HollwareConfig, OperationByName, OperationName, ResolvedSite, Scope, Verdict, describeSite, getEntry, getTranslations, listEntries } from "@hollware/core";
 import * as z from "zod";
 import { WorkerEntrypoint } from "cloudflare:workers";
-//#region src/auth/types.d.ts
-/**
- * Who calls an operation. The gateway turns each request into a principal before any handler
- * runs, and the handlers check their scopes against it at call time (ADR-019).
- */
-type Principal = {
-  /** A personal token. */
-  readonly kind: 'token';
-  readonly userId: string;
-  readonly tokenId: string;
-  /** The site the token belongs to; it never reaches another one. */
-  readonly site: string;
-  /** The token's own scopes intersected with those of its user's role, as of now. */
-  readonly scopes: readonly Scope[];
-} | {
-  /** A Worker of the same account, over the RPC binding: it reads published content. */
-  readonly kind: 'binding';
-  readonly scopes: readonly ['content:read'];
-};
-//#endregion
 //#region src/ports.d.ts
 /**
  * The ports of the operation handlers: what they need from the world, as interfaces. The D1
@@ -142,6 +122,50 @@ type WriteRefusal = {
   readonly bytes: number;
   readonly limit: number;
 };
+/** The status of a review (v0.3). */
+type ReviewStatus = 'pending' | 'approved' | 'changes_requested' | 'cancelled';
+/** A request to publish a revision, and what was decided about it. */
+interface StoredReview {
+  readonly id: string;
+  readonly entryId: string;
+  readonly revisionId: string;
+  readonly status: ReviewStatus;
+  /** The warnings the person who asked acknowledged. */
+  readonly acknowledged: readonly AcknowledgedWarning[];
+  readonly requestedBy: string;
+  /** The name of the user who asked, or `null` when they gave none. */
+  readonly requestedByName: string | null;
+  readonly requestedAt: string;
+  readonly decidedBy: string | null;
+  readonly decidedAt: string | null;
+  readonly note: string | null;
+}
+/** A scheduled publication, as the cron trigger reads it. */
+interface StoredSchedule {
+  readonly entryId: string;
+  readonly scheduledAt: string;
+  /** The version the entry had once scheduled; another one means it changed since. */
+  readonly version: number;
+  readonly acknowledged: readonly AcknowledgedWarning[];
+  readonly actor: Actor;
+}
+/** One entry of a publication: what `publish` and `publishGroup` write for it. */
+interface PublishWrite {
+  readonly entryId: string;
+  readonly expectedVersion: number;
+  readonly verdict: Verdict;
+  readonly acknowledged: readonly AcknowledgedWarning[];
+  readonly actor: Actor;
+  /** What orders the entry in published listings. */
+  readonly sortKey: string;
+  /** The event of the publication, written to the outbox in the same batch (ADR-025). */
+  readonly event?: OutboxEvent | null;
+}
+/** An event for the outbox: its id and what subscribers get, as JSON. */
+interface OutboxEvent {
+  readonly id: string;
+  readonly payload: string;
+}
 interface ContentStore {
   /** The entry with that collection, locale and slug, in the given view, or `null`. */
   findEntry(site: string, ref: EntryRef, view: View): Promise<EntryView | null>;
@@ -171,7 +195,8 @@ interface ContentStore {
   } | WriteRefusal>;
   /**
    * Appends a revision and makes it the head, if the entry is still at `expectedVersion`. In
-   * one batch: the revision, its tags (only where the revision was inserted) and the entry.
+   * one batch: the revision, its tags (only where the revision was inserted), the cancellation of
+   * a pending review, which asked for another revision, and the entry.
    */
   appendRevision(site: string, write: {
     readonly entryId: string;
@@ -184,24 +209,78 @@ interface ContentStore {
   } | WriteRefusal>;
   /**
    * Publishes the head revision, if the entry is still at `expectedVersion`, and appends the
-   * publication with its verdict and acknowledged warnings.
+   * publication with its verdict and acknowledged warnings. A pending review of the entry is
+   * approved by the actor in the same batch: what it asked for is published.
+   */
+  publish(site: string, write: PublishWrite): Promise<{
+    readonly outcome: 'published';
+    readonly view: EntryView;
+  } | WriteRefusal>;
+  /**
+   * Publishes the head revisions of a group of entries in one batch, all or none (ADR-024): every
+   * entry must still be at its `expectedVersion`. A refusal names the entry that caused it.
+   */
+  publishGroup(site: string, writes: readonly PublishWrite[]): Promise<{
+    readonly outcome: 'published';
+    readonly views: readonly EntryView[];
+  } | (WriteRefusal & {
+    readonly entryId: string;
+  })>;
+  /**
+   * Schedules the publication of an entry that is not published, if it is still at
+   * `expectedVersion`: the entry becomes `scheduled` at the next version, and its schedule keeps
+   * the acknowledged warnings and the actor for the cron trigger (ADR-025).
    */
-  publish(site: string, write: {
+  schedule(site: string, write: {
     readonly entryId: string;
     readonly expectedVersion: number;
-    readonly verdict: Verdict;
+    readonly scheduledAt: string;
     readonly acknowledged: readonly AcknowledgedWarning[];
     readonly actor: Actor;
-    /** What orders the entry in published listings. */
-    readonly sortKey: string;
   }): Promise<{
-    readonly outcome: 'published';
+    readonly outcome: 'scheduled';
     readonly view: EntryView;
   } | WriteRefusal>;
+  /** The schedules whose time has come, at most 50, oldest first. */
+  dueSchedules(site: string, now: string): Promise<readonly StoredSchedule[]>;
+  /** Takes a scheduled entry back to a draft and drops its schedule. */
+  cancelSchedule(site: string, entryId: string): Promise<void>;
+  /**
+   * Asks for the head revision of an entry to be published, if the entry is still at
+   * `expectedVersion`. An entry has one pending review at most: asking again answers it.
+   */
+  requestReview(site: string, write: {
+    readonly entryId: string;
+    readonly expectedVersion: number;
+    readonly acknowledged: readonly AcknowledgedWarning[];
+    readonly actor: Actor;
+  }): Promise<{
+    readonly outcome: 'pending_review';
+    readonly review: StoredReview;
+  } | WriteRefusal>;
+  /** A review of the site, by its id, or `null`. */
+  findReview(site: string, id: string): Promise<StoredReview | null>;
+  /** The reviews of the site with this status, newest first. */
+  listReviews(site: string, query: {
+    readonly status: ReviewStatus;
+    readonly limit: number;
+  }): Promise<readonly StoredReview[]>;
+  /** Closes a pending review with a note, without publishing. */
+  requestChanges(site: string, write: {
+    readonly id: string;
+    readonly note: string;
+    readonly userId: string;
+  }): Promise<{
+    readonly outcome: 'changes_requested' | 'not_pending';
+    readonly review: StoredReview;
+  } | {
+    readonly outcome: 'not_found';
+  }>;
   /** Takes the entry off the public site and appends the unpublish. */
   unpublish(site: string, write: {
     readonly entryId: string;
     readonly actor: Actor;
+    readonly event?: OutboxEvent | null;
   }): Promise<{
     readonly outcome: 'unpublished';
     readonly view: EntryView;
@@ -212,6 +291,54 @@ interface Clock {
   now(): Date;
 }
 //#endregion
+//#region src/events/run.d.ts
+/** A message of the events Queue: the site and the id of an outbox row. */
+interface EventMessage {
+  readonly site: string;
+  readonly id: string;
+}
+/** The part of a Queue binding that sends. */
+interface EventQueue {
+  sendBatch(messages: Iterable<{
+    readonly body: EventMessage;
+  }>): Promise<unknown>;
+}
+/** The part of a Queue message the consumer uses; its body is checked before use. */
+interface EventDelivery {
+  readonly body: unknown;
+  ack(): void;
+  retry(): void;
+}
+//#endregion
+//#region src/auth/types.d.ts
+/**
+ * Who calls an operation. The gateway turns each request into a principal before any handler
+ * runs, and the handlers check their scopes against it at call time (ADR-019).
+ */
+type Principal = {
+  /** A personal token. */
+  readonly kind: 'token';
+  readonly userId: string;
+  readonly tokenId: string;
+  /** The site the token belongs to; it never reaches another one. */
+  readonly site: string;
+  /** The token's own scopes intersected with those of its user's role, as of now. */
+  readonly scopes: readonly Scope[];
+} | {
+  /** An access token of the OAuth server (ADR-026): a person, through a client they allowed. */
+  readonly kind: 'oauth';
+  readonly userId: string;
+  /** The client the person allowed: a Client ID Metadata Document URL, or a registered id. */
+  readonly clientId: string;
+  readonly site: string;
+  /** The scopes of the grant intersected with those of the user's role, as of now. */
+  readonly scopes: readonly Scope[];
+} | {
+  /** A Worker of the same account, over the RPC binding: it reads published content. */
+  readonly kind: 'binding';
+  readonly scopes: readonly ['content:read'];
+};
+//#endregion
 //#region src/ops/types.d.ts
 /**
  * The handlers of the operations (ADR-017): one per spec of `@hollware/core`, paired by type,
@@ -228,6 +355,11 @@ interface OperationContext {
   /** What the client said about itself; writes record it as the actor's meta. */
   readonly client: Readonly<Record<string, unknown>> | null;
   readonly requestId: string;
+  /**
+   * Called with the ids of the events that a write committed to the outbox, so that they reach
+   * 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 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']>>;
@@ -266,6 +398,15 @@ export interface HollwareEnv {
    * Origin the Worker answers; without it, every request fails.
    */
   readonly HOLLWARE_PUBLIC_URL: string;
+  /**
+   * The KV namespace of the OAuth server (ADR-026): its clients, grants and tokens, all by hash.
+   * Personal tokens work without it; OAuth does not.
+   */
+  readonly OAUTH_KV: KVNamespace;
+  /** The static assets of the Worker, which hold the admin at `/admin/`; without them, no admin. */
+  readonly ASSETS?: Fetcher;
+  /** The Queue of publication events (ADR-025); without it, the cron trigger delivers them. */
+  readonly EVENTS?: EventQueue;
 }
 type Output<Spec extends {
   output: z.ZodType;
@@ -294,6 +435,12 @@ export interface HollwareRpc {
 export interface HollwareWorker {
   /** MCP at `/mcp`, and the other routes of the gateway. */
   readonly fetch: (request: Request, env: HollwareEnv, ctx: ExecutionContext) => Promise<Response>;
+  /** The consumer of the events Queue (`queues.consumers` in wrangler.jsonc). */
+  readonly queue: (batch: {
+    readonly messages: readonly EventDelivery[];
+  }, env: HollwareEnv, ctx: ExecutionContext) => Promise<void>;
+  /** The cron trigger of the project (`triggers.crons` in wrangler.jsonc, every minute). */
+  readonly scheduled: (controller: ScheduledController, env: HollwareEnv, ctx: ExecutionContext) => Promise<void>;
   /** The RPC entrypoint, for the user's Worker to export under the name `Hollware`. */
   readonly Hollware: new (ctx: ExecutionContext, env: HollwareEnv) => WorkerEntrypoint<HollwareEnv> & HollwareRpc;
 }
@@ -306,4 +453,4 @@ export type CreateHollware = (config: HollwareConfig) => HollwareWorker;
  */
 export declare const createHollware: CreateHollware;
 //#endregion
-export type { Actor, Clock, ContentStore, EntrySummaryView, EntryView, Handlers, ListQuery, NewRevision, OperationContext, OperationHandler, Principal, RevisionSummary, StoredEntry, StoredPublication, StoredRevision, View, WriteRefusal };
+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 };