@kernhq/module-quire 0.11.0 → 0.12.0

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,122 @@ 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 })
+
+/**
+ * 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('/')
+
 export const quireContract = {
   spaces: {
     list: baseContract
@@ -519,6 +637,189 @@ 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() })),
+    /** 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