@kernhq/module-quire 0.11.1 → 0.13.0

package/src/client/public-url.ts

@@ -0,0 +1,76 @@
+/**
+ * Where a published site lives, decided in exactly one place.
+ *
+ * The module's `public.*` procedures deliberately know nothing about this. They answer `path`
+ * relative to a publication — `''` for the front page, `guide/install` for a nested one — and take
+ * `basePath` as an argument, because one instance may serve a site under this prefix and another
+ * under a domain of its own. That is the right call on the server and it leaves somebody having to
+ * decide the address, so this file is that somebody: the share dialog shows what it returns, the
+ * header link opens it, and whatever route eventually renders a published page has to match it.
+ *
+ * **`/p/` is a literal segment before the workspace, not after it.** Every other Kern URL starts
+ * with the workspace — `/{workspace}/quire/{space}/{page}` — and a published site cannot, because
+ * the shell's top-level route is `[ws]`: `/{workspace}/p/…` would be inside the signed-in app,
+ * behind its guard, which is the one thing a public URL must not be. A static first segment sorts
+ * ahead of a dynamic one in SvelteKit, so `/p/…` is reachable signed out and cannot be shadowed by
+ * a workspace. The cost is that a workspace whose slug is exactly `p` would collide, which is why
+ * the segment is here as a constant rather than typed out at three call sites.
+ *
+ * **The workspace is named by id, and it was named by slug until that address stopped resolving.**
+ * A slug is the nicer half of the trade — a customer publishing a handbook is publishing a URL they
+ * will print — and it is only nicer if it works. Turning a slug into the workspace id the public
+ * procedures require is a lookup nothing can do signed out: every workspace read in `core` is
+ * behind a membership check, and a published site has no member reading it. So the route layer
+ * accepts the id form and refuses everything else, and this dialog was handing customers an address
+ * that answered 404 in every deployment that is not the mock — measured by copying the link out of
+ * the share dialog and fetching it.
+ *
+ * The id is not a secret: it is already the first segment of the API path the address resolves to,
+ * and it names a tenant rather than anything inside one. When `core` grows a signed-out
+ * `workspaces.publicBySlug`, the slug form becomes correct as well and this is the one function
+ * that has to change.
+ */
+export const PUBLIC_SITE_PREFIX = 'p'
+
+export interface PublicSiteAddress {
+  /** the workspace's id, which is what the public procedures resolve a tenant by */
+  workspaceId: string
+  /** the publication's slug */
+  slug: string
+  /**
+   * A page's path *inside* the publication, as `public.site` and `public.page` report it. `''` is
+   * the front page, which is the whole of what the share dialog ever shows.
+   */
+  path?: string
+}
+
+/**
+ * `/p/<workspace>/<publication>` — **no trailing slash**, both segments already encoded.
+ *
+ * The route serves the canonical form without one and answers the trailing-slash form with a 308,
+ * so a base that ended in `/` put an extra hop into every link a customer printed or pasted.
+ *
+ * This is not the `basePath` argument `public.page` takes: that one has to start *and* end with a
+ * slash, and the route layer builds it from this by adding one.
+ */
+export function publicSiteBasePath({ workspaceId, slug }: PublicSiteAddress): string {
+  return `/${PUBLIC_SITE_PREFIX}/${encodeURIComponent(workspaceId)}/${encodeURIComponent(slug)}`
+}
+
+/**
+ * The address to show somebody, absolute when there is an origin to be absolute against.
+ *
+ * `location` is read defensively rather than assumed: this module's client is source, built by the
+ * consumer, and a consumer that renders a screen on the server has no `location` at all. A relative
+ * address is still correct there — it is only the *copyable* one that has to be absolute.
+ */
+export function publicSiteUrl(address: PublicSiteAddress, origin?: string): string {
+  const root = origin ?? (typeof location === 'undefined' ? '' : location.origin.replace(/\/+$/, ''))
+  const trail = (address.path ?? '')
+    .split('/')
+    .filter((segment) => segment.length > 0)
+    .map(encodeURIComponent)
+    .join('/')
+  const base = `${root}${publicSiteBasePath(address)}`
+  return trail ? `${base}/${trail}` : base
+}

package/src/client/query.ts

@@ -38,6 +38,22 @@ export const quireKeys = {
   recents: (workspaceId: string) => ['quire', 'recent', workspaceId] as const,
   watchers: (workspaceId: string, pageId: string) => ['quire', 'watcher', workspaceId, pageId] as const,
 
+  /**
+   * Who has published what.
+   *
+   * `publication` is the entity `publications.create|update|remove` announce, so every screen
+   * holding one of these keys redraws when somebody else publishes or takes a site down — which
+   * matters more here than anywhere else in the module, because the thing that changed is whether
+   * strangers can read a page.
+   *
+   * `site` is under the same entity on purpose. It is the *anonymous* read of a published site —
+   * what the share dialog checks the URL against — and it is stale the instant the publication
+   * changes, so it must be invalidated by the same announcement rather than by remembering to.
+   */
+  publications: (workspaceId: string, spaceId: string) =>
+    ['quire', 'publication', workspaceId, spaceId] as const,
+  site: (workspaceId: string, slug: string) => ['quire', 'publication', workspaceId, 'site', slug] as const,
+
   /** the schema — properties and views — which every open tab of a database is drawing */
   database: (workspaceId: string, databaseId: string) =>
     ['quire', 'database', workspaceId, databaseId] as const,

package/src/contract/models.ts

@@ -87,6 +87,30 @@ export const PageNode = z.object({
   icon: z.string().nullable(),
   hasChildren: z.boolean(),
   archivedAt: Timestamp.nullable(),
+  /**
+   * Kept out of every publication, present and future — `publications.optOut` sets it.
+   *
+   * On the node rather than on `Page` because the only screen that reads it is a *list*: the share
+   * dialog draws one row per descendant with a switch on it, and a switch whose state has to be
+   * fetched page by page is a screen that opens with everything wrong and corrects itself. Two more
+   * booleans on a row the sidebar already loads for the whole space is the cheap end of that trade.
+   *
+   * `.default(false)` so a tree drawn by a client newer than its server still parses; the inferred
+   * output type is required either way, which is what makes both constructors supply it.
+   */
+  excludedFromPublic: z.boolean().default(false),
+  /**
+   * Whether a reader without edit rights has anything to be served — `publishedVersionId != null`,
+   * as a boolean, because the id itself addresses `versions.get` and a tree row has no business
+   * carrying it.
+   *
+   * Here for the same list as the flag above, and it is the half that stops that list lying. An
+   * opt-out switch on its own says "this page is public" about a page nobody has ever published,
+   * which is the wrong answer in the safe direction — and a screen that is wrong in the safe
+   * direction today is one nobody checks tomorrow. Always false for a `live` doc and a `database`:
+   * neither has a published version, because `publishing.publish` refuses anything but a `page`.
+   */
+  hasPublishedVersion: z.boolean().default(false),
 })
 export type PageNode = z.infer<typeof PageNode>
 
@@ -244,4 +268,57 @@ export const Watcher = z.object({
 })
 export type Watcher = z.infer<typeof Watcher>
 
+/**
+ * How a published site is coloured. `auto` follows the reader's own setting rather than the
+ * author's, which is the only one of the three that is a preference and not an instruction.
+ */
+export const PublicationTheme = z.enum(['auto', 'light', 'dark'])
+export type PublicationTheme = z.infer<typeof PublicationTheme>
+
+/**
+ * A page, and everything under it, at a URL a signed-out stranger can open.
+ *
+ * The row *is* the grant: no publication, no public page, and deleting it takes the site down. What
+ * a reader is served is the **pinned published version** of each page — `Page.publishedVersionId`
+ * and the HTML rendered onto it — never the live document and never the draft. A page with no
+ * published version is not public, whatever the tree says.
+ *
+ * There is no `passwordHash` here and there never should be. `hasPassword` is the whole of what a
+ * client needs: whether to ask. A hash is a hash, a salt and a cost, and shipping it to a browser
+ * turns an online guess into an offline one.
+ */
+export const Publication = z.object({
+  id: Id,
+  workspaceId: WorkspaceId,
+  /** the page the site is rooted at; its own published version is the front page */
+  rootPageId: Id,
+  /** false publishes exactly one page, which is what a single shared document wants */
+  includeDescendants: z.boolean(),
+  /**
+   * The URL segment. Unique per workspace and not beyond it — the public URL carries the workspace,
+   * so two customers both wanting `handbook` is not a collision. Lowercase by the same rule as
+   * `Space.key`: a URL that differs only in case is one URL to a person and two rows to Postgres.
+   */
+  slug: z
+    .string()
+    .min(2)
+    .max(64)
+    .regex(/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/, 'lowercase letters, digits and dashes'),
+  /** whether a password is set — never the hash, and never the password */
+  hasPassword: z.boolean(),
+  /** null never expires; past means the URL is gone */
+  expiresAt: Timestamp.nullable(),
+  /** what a search result and a link preview say; empty falls back to the root page's own title */
+  seoTitle: z.string().max(200),
+  seoDescription: z.string().max(500),
+  ogImageUrl: z.string().max(2048).nullable(),
+  /** false sends `noindex`. Public and findable are different requests, and people mean both. */
+  indexable: z.boolean(),
+  theme: PublicationTheme,
+  createdBy: UserId.nullable(),
+  createdAt: Timestamp,
+  updatedAt: Timestamp,
+})
+export type Publication = z.infer<typeof Publication>
+
 export const Ok = z.object({ ok: z.literal(true) })

package/src/contract/permissions.ts

@@ -101,9 +101,25 @@ export const quirePermissions = definePermissions([
  *     scope yet: `spaces.create` has no space to be scoped to.
  *   - `filter` — a list that omits what you may not see rather than refusing. "You may not open it"
  *     is a worse answer than not showing it, and `spaces.list` is deliberately the second.
+ *   - `public` — there is no principal to ask about. See below.
+ *
+ * **`public` is the one that needs saying out loud.** Every other value here answers "which scope is
+ * this permission resolved at"; `public` answers "this procedure asks nobody anything", which is a
+ * different kind of statement and the only one in this module that can leak a customer's private
+ * pages to the internet. It is spelled as a value rather than an omission so that adding one is a
+ * line in a review instead of a missing entry nobody sees, and `authz.int.test.ts` treats it as its
+ * own case: it calls the procedure once as a principal denied everything and once as a genuine
+ * anonymous stranger, and fails unless the two answers are byte-for-byte identical. That is the
+ * property that matters — a public surface that quietly shows an author more than it shows a
+ * stranger is one whose author tests it and never sees what the world sees.
+ *
+ * `permission` is still required for a `public` entry, and it names the permission that had to be
+ * held to *create the grant* — `quire.page.publish`, the one somebody used to make the publication.
+ * It is not a check this procedure performs. `module.test.ts` holds every entry to a permission the
+ * module declares, and there is no honest way to write "none" that keeps the rest of that check.
  */
 export interface ProcedureAuthz {
-  check: 'page' | 'space' | 'workspace' | 'filter'
+  check: 'page' | 'space' | 'workspace' | 'filter' | 'public'
   permission: string
 }
 
@@ -191,4 +207,41 @@ export const quireProcedureAuthz: Record<string, ProcedureAuthz> = {
 
   'publishing.publish': { check: 'page', permission: 'quire.page.publish' },
   'publishing.revert': { check: 'page', permission: 'quire.page.edit' },
+
+  /*
+   * A publication hands a page's whole subtree to the internet, so the question every one of these
+   * asks is about the **root page** — not the space, and not the workspace. `quire.page.publish` is
+   * already the permission that decides which version readers are served; deciding that the readers
+   * include everybody is the same decision one step further.
+   *
+   * `list` is the exception and is space-scoped, because "what has this space published" has no one
+   * page to resolve against. It filters as well: a publication whose root page the caller may not
+   * read is not named in the answer, for the same reason `pages.trash` does not name a title.
+   *
+   * `optOut` is `quire.page.publish` rather than `quire.page.edit` on purpose. Marking a page
+   * "never public" is a publishing decision about who may read it, not a change to what it says —
+   * and the two permissions are held by different people in a space where writing is open and
+   * publishing is not.
+   */
+  'publications.list': { check: 'space', permission: 'quire.page.publish' },
+  'publications.get': { check: 'page', permission: 'quire.page.publish' },
+  'publications.create': { check: 'page', permission: 'quire.page.publish' },
+  'publications.update': { check: 'page', permission: 'quire.page.publish' },
+  'publications.remove': { check: 'page', permission: 'quire.page.publish' },
+  'publications.optOut': { check: 'page', permission: 'quire.page.publish' },
+
+  /*
+   * The signed-out surface. Nothing here asks a permission, because there is nobody to ask about —
+   * see the note on `check: 'public'` above. What stands in for the permission check is that every
+   * query is scoped by the **publication**: its root page, the descendants that survive the prune,
+   * `excluded_from_public` false and a rendered published version. Workspace scope is what
+   * row-level security gives, and workspace scope is not publication scope.
+   */
+  'public.site': { check: 'public', permission: 'quire.page.publish' },
+  'public.page': { check: 'public', permission: 'quire.page.publish' },
+  'public.search': { check: 'public', permission: 'quire.page.publish' },
+  'public.sitemap': { check: 'public', permission: 'quire.page.publish' },
+  'public.robots': { check: 'public', permission: 'quire.page.publish' },
+  'public.asset': { check: 'public', permission: 'quire.page.publish' },
+  'public.unlock': { check: 'public', permission: 'quire.page.publish' },
 }

package/src/contract/router.ts

@@ -1,4 +1,4 @@
-import { baseContract, Id, PageInput, page, UserId, WorkspaceId } from '@kernhq/contracts'
+import { baseContract, Id, PageInput, page, Timestamp, UserId, WorkspaceId } from '@kernhq/contracts'
 import { z } from 'zod'
 import {
   CommentAnchor,
@@ -11,6 +11,8 @@ import {
   PageKind,
   PageNode,
   PageVersion,
+  Publication,
+  PublicationTheme,
   RecentView,
   RichDoc,
   Space,
@@ -67,6 +69,175 @@ export const WatchState = z.object({
 })
 export type WatchState = z.infer<typeof WatchState>
 
+/**
+ * A published site addresses its pages by **path, never by id**, and that is a security decision
+ * rather than a matter of taste.
+ *
+ * Every id in a public response is a string somebody can try somewhere else, and the only way to be
+ * sure none of them opens a door is for there to be none. So the whole `public.*` surface below
+ * carries no page id, no space id, no version id, no user id and no workspace id — a nav entry, a
+ * breadcrumb, a search hit and a sitemap line are all `path`, and `path` is built from titles by the
+ * server. `publications.int.test.ts` walks every public response and fails on any uuid belonging to
+ * anything in the fixture, which is what keeps this true as the shapes grow.
+ *
+ * The root page's path is the empty string; a child's is its ancestors' slugs joined with `/`, each
+ * slug being its title reduced to letters, digits and dashes (Unicode letters, so a Persian title
+ * keeps a Persian slug) and suffixed `-2`, `-3` when two siblings would collide.
+ */
+export const PublicNavEntry = z.object({
+  /** '' is the front page; everything else is `parent/child`, already URL-safe once encoded */
+  path: z.string(),
+  /** null only for the front page — the nav is flat, like `pages.tree`, and rebuilt into a tree */
+  parentPath: z.string().nullable(),
+  title: z.string(),
+  icon: z.string().nullable(),
+})
+export type PublicNavEntry = z.infer<typeof PublicNavEntry>
+
+/** What is worth saying about a published site once a reader is allowed to see it. */
+export const PublicSiteDetail = z.object({
+  title: z.string(),
+  description: z.string(),
+  ogImageUrl: z.string().nullable(),
+  /** false means the route layer sends `noindex`. Public and findable are different requests. */
+  indexable: z.boolean(),
+  /**
+   * The newest published version in the whole site.
+   *
+   * Deliberately *not* the newest `pages.updated_at`: that column moves on every keystroke in a
+   * draft, so publishing it would tell the internet when somebody was working on an unpublished
+   * change. A published site's freshness is when something was last published.
+   */
+  updatedAt: Timestamp,
+  nav: z.array(PublicNavEntry),
+})
+export type PublicSiteDetail = z.infer<typeof PublicSiteDetail>
+
+/**
+ * A published site, or the door to it.
+ *
+ * `locked` is the one thing a password-protected site admits before the password: that there is a
+ * door. Everything else — the title, the description, the shape of the tree — is behind it, because
+ * a nav tree is a table of contents and a table of contents is most of what a private handbook is.
+ * `theme` comes out anyway so the challenge screen is not white on a site that is not.
+ */
+export const PublicSite = z.object({
+  slug: z.string(),
+  theme: PublicationTheme,
+  locked: z.boolean(),
+  /** null exactly when `locked` */
+  site: PublicSiteDetail.nullable(),
+})
+export type PublicSite = z.infer<typeof PublicSite>
+
+export const PublicBreadcrumb = z.object({ path: z.string(), title: z.string() })
+export type PublicBreadcrumb = z.infer<typeof PublicBreadcrumb>
+
+export const PublicPage = z.object({
+  path: z.string(),
+  title: z.string(),
+  icon: z.string().nullable(),
+  coverUrl: z.string().nullable(),
+  /**
+   * The pinned published version, drawn once and stored on the version — never the live document
+   * and never the draft — then passed through the public scrub: every `id` and `data-id` attribute
+   * removed, and every page mention either re-pointed at its public path or left as plain text.
+   */
+  html: z.string(),
+  publishedAt: Timestamp,
+  /**
+   * A cache validator for the pinned version, and **not the version's id**.
+   *
+   * A published page is immutable, so the response is a static read that should be cached until the
+   * page is published again — which is what an entity tag is for. It is a hash rather than the id
+   * because the id addresses `versions.get`, a procedure that asks a permission: handing it to the
+   * internet turns a cache key into something to try.
+   */
+  etag: z.string(),
+  breadcrumbs: z.array(PublicBreadcrumb),
+})
+export type PublicPage = z.infer<typeof PublicPage>
+
+export const PublicSearchHit = z.object({
+  path: z.string(),
+  title: z.string(),
+  /** plain text from the published version, never from the draft */
+  snippet: z.string(),
+})
+export type PublicSearchHit = z.infer<typeof PublicSearchHit>
+
+export const PublicSitemapEntry = z.object({ path: z.string(), lastModified: Timestamp })
+
+/**
+ * One picture from a published page, **as bytes rather than as an address**.
+ *
+ * A published page used to carry its pictures as presigned storage URLs, written into the stored
+ * HTML at publish time. That was wrong twice over, and both halves were measured rather than
+ * argued. The URL is the storage key — `ws/<workspaceId>/<module>/<yyyy>/<mm>/<fileId>/<name>` —
+ * so every published page with a picture on it handed a stranger the tenant's workspace uuid and a
+ * file uuid, on the one surface whose whole rule is that no response carries an id; and a presigned
+ * GET expires in an hour while the HTML it was baked into is rendered once and stored for ever, so
+ * every image on every published site broke sixty minutes after it was published.
+ *
+ * So the HTML carries an opaque, workspace-sealed reference and the bytes come through here. The
+ * route layer fetches this from **its own server** and streams the body back under a URL of its
+ * own; nothing in the answer may reach a browser as-is, which is why it is bytes and not a link —
+ * there is no address in it to leak, and none to expire.
+ *
+ * Capped rather than streamed on purpose: a published handbook's illustration is tens of kilobytes,
+ * this path is anonymous, and an unbounded body on an unauthenticated endpoint is a way to spend
+ * somebody else's memory. Over the cap answers the same 404 as a picture that is not there.
+ */
+export const PublicAsset = z.object({
+  /**
+   * The stored content type, narrowed to an image type before it is answered.
+   *
+   * The route layer serves these from the application's own origin, so the two things it owes back
+   * are `X-Content-Type-Options: nosniff` and, because `image/svg+xml` is a document that can carry
+   * script, a `Content-Security-Policy: default-src 'none'` on the response. Anything the server
+   * could not narrow to an image is refused here rather than sent for the route layer to be careful
+   * with.
+   */
+  contentType: z.string(),
+  /** base64 of the whole object */
+  bytes: z.string(),
+  /** how long the route layer may cache it; a version is immutable, so this is long */
+  maxAge: z.number().int().min(0),
+})
+export type PublicAsset = z.infer<typeof PublicAsset>
+
+/**
+ * The URL prefix the route layer serves this site under, so a link between two published pages is a
+ * link and not a dead mention.
+ *
+ * The module knows a page's path inside its publication and nothing about the address it is served
+ * at — one instance mounts a site at `/p/<workspace>/<slug>/`, another at the root of its own
+ * domain. Rather than guess, it takes the prefix and refuses anything that is not one: it has to
+ * start and end with `/`, and its segments are unreserved characters only. That refusal is the
+ * point. `//evil.example/` is a protocol-relative URL wearing the costume of a local path, and a
+ * caller that could set it would have every link on somebody's published site point off-site.
+ */
+export const PublicBasePath = z
+  .string()
+  .max(200)
+  .regex(/^\/(?:[A-Za-z0-9._~-]+\/)*$/, 'an absolute path ending in a slash')
+  .default('/')
+
+/**
+ * The one thing the module does ask of whatever serves a published site: a place for its pictures.
+ *
+ * `public.page` writes every `<img src>` as `<basePath><segment>/<reference>`, so the route layer
+ * has to answer that address by calling `public.asset` and streaming the bytes back. It is a
+ * constant rather than a convention because two sides have to agree on it and only one of them can
+ * be wrong quietly — a route layer that does not serve it renders a published page with no
+ * pictures, which looks like a rendering bug and is a missing route.
+ *
+ * The leading `__` is what keeps it out of the way: a page's own path segment is `slugifyTitle`'s
+ * output, which is Unicode letters and digits separated by hyphens, so no title can ever produce a
+ * segment starting with an underscore and no published page can be shadowed by this one.
+ */
+export const PUBLIC_ASSET_SEGMENT = '__media'
+
 export const quireContract = {
   spaces: {
     list: baseContract
@@ -519,6 +690,214 @@ export const quireContract = {
       .input(ws.extend({ pageId: Id }))
       .output(Page),
   },
+
+  /**
+   * Who has published what, from the inside. Every procedure here is authenticated and asks
+   * `quire.page.publish` about the **root page**, because that is the page whose subtree is being
+   * handed to the internet.
+   */
+  publications: {
+    list: baseContract
+      .route({ method: 'GET', path: '/spaces/{spaceId}/publications', ...t('publications') })
+      .input(ws.extend({ spaceId: Id }))
+      .output(z.array(Publication)),
+    get: baseContract
+      .route({ method: 'GET', path: '/publications/{publicationId}', ...t('publications') })
+      .input(ws.extend({ publicationId: Id }))
+      .output(Publication),
+    create: baseContract
+      .route({ method: 'POST', path: '/publications', ...t('publications') })
+      .input(
+        ws.extend({
+          rootPageId: Id,
+          slug: Publication.shape.slug,
+          includeDescendants: z.boolean().default(true),
+          /** the password itself, once; the server keeps a hash and never gives one back */
+          password: z.string().min(6).max(200).nullable().default(null),
+          expiresAt: Timestamp.nullable().default(null),
+          seoTitle: z.string().max(200).default(''),
+          seoDescription: z.string().max(500).default(''),
+          ogImageUrl: z.string().max(2048).nullable().default(null),
+          indexable: z.boolean().default(true),
+          theme: PublicationTheme.default('auto'),
+        }),
+      )
+      .output(Publication),
+    /**
+     * `password` is three-valued on purpose: a string sets one, `null` removes it, and leaving the
+     * key out changes nothing. A two-valued field would make every "rename the site" request also
+     * an "unlock the site" request, which is the shape that quietly takes the door off a handbook.
+     */
+    update: baseContract
+      .route({ method: 'PATCH', path: '/publications/{publicationId}', ...t('publications') })
+      .input(
+        ws.extend({
+          publicationId: Id,
+          slug: Publication.shape.slug.optional(),
+          includeDescendants: z.boolean().optional(),
+          password: z.string().min(6).max(200).nullable().optional(),
+          expiresAt: Timestamp.nullable().optional(),
+          seoTitle: z.string().max(200).optional(),
+          seoDescription: z.string().max(500).optional(),
+          ogImageUrl: z.string().max(2048).nullable().optional(),
+          indexable: z.boolean().optional(),
+          theme: PublicationTheme.optional(),
+        }),
+      )
+      .output(Publication),
+    /** The row is the grant, so removing it takes the site down. Nothing else is deleted. */
+    remove: baseContract
+      .route({ method: 'DELETE', path: '/publications/{publicationId}', ...t('publications') })
+      .input(ws.extend({ publicationId: Id }))
+      .output(Ok),
+    /**
+     * Keep one page — and therefore everything under it — out of every publication, present and
+     * future.
+     *
+     * Absolute rather than per-publication, and that is the whole reason it is a flag on the page:
+     * an opt-out recorded against one publication says nothing about a publication somebody roots
+     * above the page next month, and its author would never see it. This one holds against
+     * publications that do not exist yet.
+     */
+    optOut: baseContract
+      .route({ method: 'POST', path: '/pages/{pageId}/public-opt-out', ...t('publications') })
+      .input(ws.extend({ pageId: Id, excluded: z.boolean().default(true) }))
+      .output(z.object({ pageId: Id, excluded: z.boolean() })),
+  },
+
+  /**
+   * The signed-out surface. **This is the only part of Kern with no principal behind it.**
+   *
+   * Five rules hold here, and each of them is a test in `publications.int.test.ts`:
+   *
+   *   1. A page is public only if it is inside the publication's subtree, not opted out, not
+   *      archived, not trashed, and has a published version that has been rendered. Failing any one
+   *      of those is **404, never 403** — a refusal that distinguishes "not yours" from "not there"
+   *      confirms the page exists to whoever is guessing.
+   *   2. Guessing a sibling, a parent, a page in another space or another workspace gets 404 too,
+   *      which is free here because nothing is addressed by id: `path` names a place in *this*
+   *      publication's tree or it names nothing.
+   *   3. No response carries a draft, a comment, an author, a version list, or any id.
+   *   4. A password-protected publication answers a challenge and nothing else. `unlock` mints a
+   *      **capability token, not a session**: an AES-GCM envelope sealed with the instance secret,
+   *      bound by its associated data to this one publication, carrying an expiry and no identity.
+   *      The server keeps nothing. The route layer is expected to hold it in an HttpOnly cookie and
+   *      pass it back — never to put it in a link, because a token in a URL is a token in a referrer
+   *      header and in somebody's access log.
+   *   5. An expired publication is 404, checked on the request rather than by a sweep.
+   *
+   * `workspaceId` is in the path because *anonymous means no principal, not no tenant*: the request
+   * has to name a workspace before anything touches `mod_quire`, or row-level security has nothing
+   * to fence with. See the note at the top of `migrations/0008_publications.sql`.
+   */
+  public: {
+    site: baseContract
+      .route({ method: 'GET', path: '/public/{workspaceId}/{slug}', ...t('public') })
+      .input(
+        z.object({
+          workspaceId: WorkspaceId,
+          slug: Publication.shape.slug,
+          token: z.string().max(4096).nullable().default(null),
+        }),
+      )
+      .output(PublicSite),
+    /**
+     * One page of a published site.
+     *
+     * `path` is a query parameter rather than a path segment because it contains slashes: a nested
+     * page's address is `guide/install`, and oRPC's route matcher takes one segment per parameter.
+     */
+    page: baseContract
+      .route({ method: 'GET', path: '/public/{workspaceId}/{slug}/page', ...t('public') })
+      .input(
+        z.object({
+          workspaceId: WorkspaceId,
+          slug: Publication.shape.slug,
+          /** '' is the front page */
+          path: z.string().max(1024).default(''),
+          basePath: PublicBasePath,
+          token: z.string().max(4096).nullable().default(null),
+        }),
+      )
+      .output(PublicPage),
+    /**
+     * Search inside this publication and nowhere else.
+     *
+     * It reads the **published version's** flattened text, not `pages.text`. That column mirrors the
+     * live document, so searching it would put a sentence somebody has not published yet into a
+     * snippet on the public internet — the one place in this module where the draft and the
+     * published copy differ and the difference is the whole point.
+     */
+    search: baseContract
+      .route({ method: 'GET', path: '/public/{workspaceId}/{slug}/search', ...t('public') })
+      .input(
+        z.object({
+          workspaceId: WorkspaceId,
+          slug: Publication.shape.slug,
+          q: z.string().min(2).max(200),
+          limit: z.number().int().min(1).max(50).default(20),
+          token: z.string().max(4096).nullable().default(null),
+        }),
+      )
+      .output(z.object({ items: z.array(PublicSearchHit) })),
+    /**
+     * What a crawler may index, which is not the same list as what a reader may open: a site behind
+     * a password, or marked `indexable: false`, has an empty sitemap rather than a private one.
+     */
+    sitemap: baseContract
+      .route({ method: 'GET', path: '/public/{workspaceId}/{slug}/sitemap', ...t('public') })
+      .input(z.object({ workspaceId: WorkspaceId, slug: Publication.shape.slug }))
+      .output(z.object({ entries: z.array(PublicSitemapEntry) })),
+    /**
+     * The one procedure here that never distinguishes one slug from another.
+     *
+     * A crawler asking about a slug that does not exist, one that has expired, and one behind a
+     * password must all get the same answer, or `robots` becomes the oracle every other procedure
+     * refuses to be. So it succeeds for all three and says "do not index". (A workspace with the
+     * module switched off is still a 404, from the middleware — that is a statement about the
+     * workspace, which the path already named, and not about any slug.)
+     */
+    robots: baseContract
+      .route({ method: 'GET', path: '/public/{workspaceId}/{slug}/robots', ...t('public') })
+      .input(z.object({ workspaceId: WorkspaceId, slug: Publication.shape.slug }))
+      .output(z.object({ indexable: z.boolean(), sitemapPath: z.string().nullable() })),
+    /**
+     * The bytes of one picture on a published page.
+     *
+     * `asset` is the opaque reference the page's own HTML carries — an AES-GCM envelope sealed with
+     * the instance secret and bound by its associated data to this workspace, so it names nothing
+     * on its own and cannot be carried to another instance. Resolving it is not enough on its own:
+     * the file has to be referenced by a version that is *currently* public in this publication, so
+     * opting a page out stops its pictures resolving in the same breath as its prose.
+     *
+     * Everything unresolvable is the same 404 as everything else here — a reference that will not
+     * decrypt, one for a file nothing public uses, a file that has been deleted, an object over the
+     * cap. And a locked publication answers the door first: the pictures are behind the password
+     * along with the pages they are on.
+     */
+    asset: baseContract
+      .route({ method: 'GET', path: '/public/{workspaceId}/{slug}/asset', ...t('public') })
+      .input(
+        z.object({
+          workspaceId: WorkspaceId,
+          slug: Publication.shape.slug,
+          asset: z.string().min(1).max(2048),
+          token: z.string().max(4096).nullable().default(null),
+        }),
+      )
+      .output(PublicAsset),
+    /** Present the password, get a token. A site with no password has no door, and answers 404. */
+    unlock: baseContract
+      .route({ method: 'POST', path: '/public/{workspaceId}/{slug}/unlock', ...t('public') })
+      .input(
+        z.object({
+          workspaceId: WorkspaceId,
+          slug: Publication.shape.slug,
+          password: z.string().min(1).max(200),
+        }),
+      )
+      .output(z.object({ token: z.string(), expiresAt: Timestamp })),
+  },
 } as const
 export type QuireContract = typeof quireContract