@hollware/server 0.2.0 → 0.4.0

package/dist/ceremonies-V_1BbmZQ.mjs

@@ -0,0 +1,150 @@
+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-CsuER6J7.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, 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, 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, {
+			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, {
+		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, 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: invitation.site,
+		now: ceremony.now
+	});
+	const { credential } = verified.registrationInfo;
+	await addPasskey(ceremony.db, {
+		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, {
+		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 deployment, 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, {
+			challenge: options.challenge,
+			purpose: "authenticate",
+			invitationId: null,
+			userId: null,
+			now: ceremony.now
+		}),
+		options
+	};
+}
+/** 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, {
+		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, 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, {
+		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

@@ -122,6 +122,24 @@ 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;
@@ -177,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;
@@ -190,7 +209,8 @@ 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';
@@ -225,6 +245,37 @@ interface ContentStore {
   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;
@@ -273,6 +324,26 @@ type Principal = {
   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 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';
@@ -338,6 +409,13 @@ 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;
 }
@@ -386,4 +464,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, RevisionSummary, StoredEntry, StoredPublication, StoredRevision, StoredSchedule, 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 };