@bloklabs/server 1.16.0 → 2.0.0

package/README.md

@@ -2,6 +2,12 @@
 
 Blok's shared server is written in C#. It handles file uploads, link previews and live collaboration, and it converts saved documents. Use it inside an ASP.NET Core app, or run the same routes as a standalone npm binary or Docker image.
 
+A Go version of the server lives in `packages/server/go`. It serves the same routes as the C# server. Every conformance suite runs against both. It serves health, link previews (`/unfurl`), uploads (`/upload`, `/upload-by-url`), deletes and local files. Its `blokdocs` package converts saved documents. With `--collab` it also serves live collaboration: the sync socket, `/edit`, `/state`, `/reset` and the history routes. It reads and writes the same collaboration directory as the C# server.
+
+The npm binary, the Docker image and the NuGet packages all ship the C# server. See [Go module and archives](#go-module-and-archives) for how the Go server ships.
+
+A Rust build is in progress in `packages/server/rust`. It ships nothing yet. Its README is `packages/server/rust/README.md`.
+
 Your documents stay yours. Your own app saves and loads them through a small endpoint, and that endpoint stays the record. With live collaboration on, the service keeps only a working copy of each open document. The copy lives in storage you point it at. Every few seconds, the service writes what people type back to your endpoint.
 
 Register an operation journal and that changes. The document keeps no working copy. The journal is where an edit becomes durable. Your endpoint's record is refreshed from a published checkpoint, on eviction and on drain, rather than on a timer. The packages include no database-block or MySQL integration; those follow this delivery migration.
@@ -36,6 +42,23 @@ The mapped group uses your ASP.NET Core authorization policy for upload and unfu
 
 In-process defaults expose health only. Storage and outbound routes must be enabled explicitly, and local storage requires an explicit valid `PublicUrl`. `AddBlokServer(options => { ... })` also accepts the origin, upload-limit, and S3 settings used by the standalone host.
 
+### Refuse bare LF line ends
+
+By default Kestrel takes a bare LF (no CR) at the end of a chunked trailer line. Every other chunk line needs CRLF. A proxy in front of your app may read that trailer another way. The proxy and Kestrel then disagree on where the next request starts, and a request can be smuggled past the proxy.
+
+The standalone host turns this off. Your own app does not get that setting from `AddBlokServer` or `MapBlokServer`, because it is a Kestrel runtime switch. Set it in your app's project file:
+
+```xml
+<ItemGroup>
+  <RuntimeHostConfigurationOption Include="Microsoft.AspNetCore.Server.Kestrel.DisableHttp1LineFeedTerminators"
+                                  Value="true" />
+</ItemGroup>
+```
+
+The switch covers all of Kestrel's HTTP/1 parsing. The request line and the headers then need CRLF too. A request with a bare LF gets an empty 400, and the connection closes.
+
+The Go and Rust hosts refuse bare LF line ends as well.
+
 ## Convert documents
 
 `Blok.Server` embeds Blok's own serializer as a JavaScript bundle and runs it in this process. A document therefore converts through the editor's implementation, not a port of it. A port has to be taught every block Blok gains, and it silently drops the ones nobody remembered.
@@ -217,6 +240,16 @@ docker run \
 
 `--collab` turns the sync routes on. `--doc-endpoint` names the routes in your own app that the service loads a document from and writes it back to. `BLOK_DOC_ENDPOINT_AUTH` holds the header value those routes expect, sent verbatim on every call. It has to be a single line: a value carrying a carriage return or newline refuses to start rather than losing the header on every call. `--collab-dir` (or `--collab-s3-prefix`) is where the working copy lives. It holds document content, so it must not be publicly readable, and it may not sit inside `--storage-dir`, where everything is served. In-process, the same switches are `options.CollabEnabled` and `options.DocEndpoint`, and the app must call `app.UseWebSockets()`.
 
+A document also carries its page title and icon as top-level `title` and `icon` keys, for example `{"blocks": [...], "title": "Plan", "icon": {"type": "emoji", "value": "🚀"}}`. The service seeds a room from them, and writes them back on every PUT and on `GET /sync/{doc}/state`. A key is left out when the page has none. A malformed value is dropped, not refused: a title must be a non-empty string, and an icon `{"type": "emoji", "value": "…"}` or `{"type": "image", "url": "…"}`. A title or icon that holds a NUL (U+0000), say from an older client, is left out of the write-back the same way. A dropped value is gone from your record after the next write-back, because that PUT leaves the key out. A reset reseeds from your record, so a title change newer than the last PUT is lost, the same as a block edit.
+
+**Breaking.** The write-back now carries the page title and icon. Before, the service read only `blocks` from your record, and the PUT body and `GET /sync/{doc}/state` held only `time` and `blocks`. Now the service seeds the room from your record's top-level `title` and `icon`, and sends both back on every write-back. This affects a host that keeps its own top-level `title` or `icon` with another meaning. It also affects a host that renames a page outside the room: the next PUT overwrites the new name with the room's title, or leaves the key out when the room has none.
+
+What to change in your app:
+
+- If your top-level `title` or `icon` means something else, rename your field.
+- Otherwise treat the PUT's `title` and `icon` as Blok's page title and icon, and save them.
+- Rename a page through an editor in the room, with `title.set`. The room reads your record only when it seeds, so a rename made only there is overwritten by the next PUT. The `/edit` endpoint cannot set the title.
+
 Documents written to your endpoint carry rich text fields as segments, the shape the editor's `save()` returns. A document your endpoint returns may hold HTML strings or segments. A custom block tool's rich fields go in `--rich-text-fields` (or `BLOK_RICH_TEXT_FIELDS`; the flag wins), as JSON keyed by block type: `--rich-text-fields '{"callout":["title"]}'`. In-process, the same list is `options.RichTextFields`. List exactly the fields the tool declares in `static richTextFields` on the client, or the two write the field in different shapes. The built-in paragraph, header, quote, toggle and list `text` fields need no entry. See [Rich text is segments](#rich-text-is-segments).
 
 Collaboration rooms are stored in format 2. Upgrade the service and the editor together. An older editor reads the format 2 room and ends its own session with `unsupported-format`. A room stored in format 1 is converted the first time it opens, and offline edits made in format 1 are not replayed.
@@ -288,12 +321,18 @@ Passes are needed whenever the routes run with `Auth = "ticket"`, including rout
 | --- | --- |
 | `GET /health` | Reports liveness and the running version |
 | `GET /unfurl?url=…` | Reads title, description, and image metadata |
+| `GET /frame-check?url=…&embedder=…` | Says whether the page would let your editor show it in a frame, plus safe oEmbed details |
 | `POST /upload` | Stores an uploaded file |
 | `POST /upload-by-url` | Fetches and stores a remote file; the request media type must be `application/json` |
 | `GET /sync/{doc}` | WebSocket; the editor's live collaboration connection to one document (with `--collab`) |
 | `POST /sync/{doc}/reset` | Drops the working copy, reloads the document from your endpoint and tells every open tab to pick it up |
 | `POST /sync/{doc}/edit` | Inserts, updates or removes blocks from outside; all-or-nothing, reaches every open tab, and requires an idempotency key |
 | `GET /sync/{doc}/state` | Returns the live document as JSON, with the journal head it reflects when there is a journal |
+| `GET /sync/{doc}/history` | Lists the document's past versions as points; needs an operation journal |
+| `GET /sync/{doc}/history/{lineage}/{sequence}` | Returns the document as it was at one point |
+| `GET /sync/{doc}/history/{lineage}/{sequence}/changes` | Lists the edits inside one version, one row per journal record |
+| `POST /sync/{doc}/history/{lineage}/{sequence}/restore` | Makes the live document match one point, as a forward edit; requires an idempotency key |
+| `DELETE /sync/{doc}/history/{lineage}` | Deletes one lineage that is not current |
 
 On a journal-backed service, `POST /sync/{doc}/reset` first adopts a working copy the journal does not hold yet and writes it back to your endpoint, so the reset rebaselines from a record that includes it. It then retires that working copy before it resets. If the retire fails, the reset answers 503 and changes nothing; retry it.
 
@@ -302,6 +341,7 @@ On a journal-backed service, `POST /sync/{doc}/reset` first adopts a working cop
 A rich text field in an edit may be an HTML string or segments. The service reads the HTML into segments before it applies anything. A rich text field is the `text` of a paragraph, header, quote, toggle or list block, plus every field in `--rich-text-fields`.
 
 - If reading that HTML runs past the runtime's timeout, the edit answers 503 with `Retry-After` (2 seconds by default) and applies nothing. Retry with the same key.
+- One HTML string may hold at most 32768 characters (UTF-16 code units). A longer one answers 413 before any of it is read. Segments have no such limit.
 - If that HTML runs out of the runtime's memory budget, the edit answers 413 and applies nothing. The budget is per request, so the same body fails every time. Do not retry it; send less rich text.
 - HTML the reader refuses answers 422.
 
@@ -323,13 +363,157 @@ An edit may also send `If-Match: "<lineage>:<sequence>"`. It is one quoted tag,
 
 `GET /sync/{doc}/state` returns the live document as `application/json`, in the same shape your document endpoint receives, with rich text fields as segments. It includes edits made a moment ago. With a journal, it also sends `Blok-Doc-Lineage`, `Blok-Doc-Sequence` and `ETag: "<lineage>:<sequence>"`, naming the exact head the body reflects. Send that `ETag` back as `If-Match` to edit only if nothing changed in between. A working-copy-only service sends the body without those three headers. A purged document answers 403. A document that cannot be loaded, is held by another process, or is on a service that is shutting down answers 503. An export that ran past the runtime's timeout or allocation budget also answers 503, with `Retry-After` (2 seconds by default). A document the service cannot write as JSON answers 500.
 
-Both routes add `Blok-Doc-Lineage`, `Blok-Doc-Sequence` and `ETag` to `Access-Control-Expose-Headers` for an allowed origin, so a browser page can read them. Headers your app already exposes are kept.
+`edit`, `state` and the history `restore` add `Blok-Doc-Lineage`, `Blok-Doc-Sequence` and `ETag` to `Access-Control-Expose-Headers` for an allowed origin, so a browser page can read them. Headers your app already exposes are kept.
+
+Upload routes exist only when local or S3-compatible storage is configured. Consumer-supplied URLs pass through one guarded outbound client that blocks private and cloud-metadata addresses. It also refuses a URL whose raw text holds a control character (C0, DEL or C1), anywhere and in every redirect `Location`. Spaces at the ends are trimmed. Send `POST /upload-by-url` a `{"url":"..."}` body with an `application/json` media type; parameters such as `charset=utf-8` are allowed, but JSON suffix types are not.
 
-Upload routes exist only when local or S3-compatible storage is configured. Consumer-supplied URLs pass through one guarded outbound client that blocks private and cloud-metadata addresses. Send `POST /upload-by-url` a `{"url":"..."}` body with an `application/json` media type; parameters such as `charset=utf-8` are allowed, but JSON suffix types are not.
+Outbound fetches follow at most 5 redirects. A redirect from `https` to `http` is refused. A response head over 64 KiB is refused. When a rate limit is on, each redirect hop counts as one more request for the caller.
+
+At most four page fetches (`/unfurl`, `/frame-check`) and four downloads (`/upload-by-url`) run at once, in separate pools, so slow downloads never hold up link checks. When a rate limit is on, one caller (client address, or ticket user) may run at most two of each at once. A third waits for one of that caller's own slots within its own deadline, and fails as any slot wait does when the deadline runs out.
+
+`GET /unfurl?url=…` answers `{"success": 1, "link": …, "meta": {"title", "description", "image": {"url"}, "favicon", "domain"}}`. A field with no value is left out, and `image` is then `{}`.
+
+- `link` is the final URL after redirects.
+- `image.url` and `favicon` are URLs a reader's browser loads. They pass the same filter as the `/frame-check` `thumbnail_url` below:
+  - They must be `https`, with no user name or password, and at most 2048 characters.
+  - A control character, raw or escaped (`%00`–`%1F`, `%7F`, `%C2%80`–`%C2%9F`), drops the URL.
+  - A loopback, private or metadata address, `localhost`, a name with no dot, a name ending in a dot and a name whose last label starts with a digit are dropped. A Unicode host comes back as punycode.
+- When a candidate is dropped, the next one is tried: `og:image`, then `twitter:image`; `rel="icon"`, then `apple-touch-icon`, then `/favicon.ico` on the final page.
+- So a page served over `http` gets no favicon, unless it names an `https` one.
+
+`GET /frame-check?url=…&embedder=…` is open whenever `/unfurl` is. It answers `{"verdict": …, "link": …, "oembed": {…}}`.
+
+- `verdict` is `allowed`, `blocked`, `insecure` or `unknown`.
+- `blocked` means the final page's enforced `Content-Security-Policy: frame-ancestors`, or its `X-Frame-Options`, refuses your editor. Report-only policies and `<meta>` tags do not count. Redirect hops do not count.
+- `insecure` means the final page is not `https`. `blocked` wins over it.
+- `unknown` means the server could not tell who your editor is, or the page could not be fetched or did not answer 2xx.
+- `embedder` is your editor page's origin, such as `https://app.example`. The editor's default check sends it. A browser sends no `Origin` on a same-origin `GET`, so this is how a service mounted on your app's own origin (say `/api/blok`) learns who is asking.
+- The server picks your editor like this:
+  1. A request that sends `Origin` uses it, when it is an allowed origin. Any other `Origin` is refused with 403 before the check runs. `embedder` is ignored.
+  2. With no `Origin`, `embedder` is used when the request carries `Sec-Fetch-Site: same-origin` and `embedder` equals the service's own origin: the request's scheme and `Host` header.
+  3. Otherwise `embedder` is used only when it is an allowed origin.
+  4. Otherwise there is no editor, and the verdict is `unknown`.
+- A page cannot set `Sec-Fetch-Site`, so a page on an unlisted site cannot get a verdict through the service. Origins compare without case, and must match exactly: no path, no trailing `/`.
+- Behind a proxy that ends TLS, the service sees `http`, not `https`. Rule 2 then fails, so add your editor's origin to the allowed origins. The Go server reads the scheme from the connection and `Host` from the request. ASP.NET Core reads `Request.Scheme` and `Request.Host`, so it follows your app if your app rewrites them.
+- In `ticket` mode every request needs an allowed `Origin`, so a same-origin check gets 403 and the editor shows `unknown`. Rule 2 helps in `none` and `proxy` modes.
+- The answer sends `Vary: Origin`.
+- `link` is the final URL after redirects.
+- `oembed` appears when the page links a JSON oEmbed endpoint. It holds only `title`, `provider_name`, an `https` `thumbnail_url`, and `width` and `height` capped at 4096. The oEmbed `html` field is never returned.
+  - `thumbnail_url` is dropped when it holds a control character, raw or escaped (`%00`–`%1F`, `%7F`, `%C2%80`–`%C2%9F`).
+  - It is also dropped when its host is a loopback, private or metadata address, `localhost`, or a name with no dot. A Unicode host comes back as punycode.
+  - The server never fetches the thumbnail. Treat it as untrusted input.
+
+The verdict is a hint for your UI, not a security check. The server cannot see the reader's cookies, the full chain of frames above your editor, or scripts that break out of frames.
 
 A request that carries `Origin` must match an allowed origin in every auth mode. In `none` and `proxy`, a genuinely originless backend request remains allowed, but an originless browser request carrying `Sec-Fetch-Site: cross-site` is rejected. `ticket` always requires an allowed `Origin`.
 
-A ticket with `write: false` may call `GET /unfurl`, `GET /sync/{doc}/state` and open `GET /sync/{doc}` read-only; both upload routes, `reset` and `edit` require `write: true`. The `doc` claim scopes the collaboration routes: `/sync/{doc}`, its `reset`, its `edit` and its `state` are refused when the pass names no document or a different one. `state` asks your `IBlokAuthorization` for read access only. A collaboration pass must also name its `user`: `GET /sync/{doc}` closes one with an empty `user` as 4401 `pass names no user`, because the per-user connection cap and rate window key on that name. The upload and unfurl routes ignore it, so a pass minted for one page works for every upload and preview that page can make.
+With `--auth none` or `proxy`, the standalone host also checks `Host` on these routes. This stops DNS rebinding: a page whose name now points at 127.0.0.1 sends its own name as `Host`.
+
+- Allowed: `localhost`, a `127.x.x.x` address and `[::1]`, with any port, and a request with no `Host`.
+- Also allowed: the host of each `--allow-origin` entry and of `--public-url`.
+- Anything else gets `421` `host not allowed`.
+
+If a front proxy forwards your public `Host`, add that origin to `--allow-origin`, or make the proxy send a loopback `Host`. Ticket mode does not check `Host`; behind a proxy that is the proxy's job.
+
+In your own ASP.NET Core app the check is off. Turn it on with `AddBlokServer(...).UseLoopbackHostCheck()` when the app listens on loopback only. Leave it off when the app serves the routes under its own public name. The Go handler has the same switch: `Options.LoopbackHostCheck`.
+
+A ticket with `write: false` may call `GET /unfurl`, `GET /frame-check`, `GET /sync/{doc}/state`, the three `GET` history routes and open `GET /sync/{doc}` read-only; both upload routes, `reset`, `edit`, the history `DELETE` and `restore` require `write: true`. The `doc` claim scopes the collaboration routes: `/sync/{doc}`, its `reset`, its `edit`, its `state` and its history routes are refused when the pass names no document or a different one. `state` and the three history reads ask your `IBlokAuthorization` for read access only. A collaboration pass must also name its `user`: `GET /sync/{doc}` closes one with an empty `user` as 4401 `pass names no user`, because the per-user connection cap and rate window key on that name. The upload and unfurl routes ignore it, so a pass minted for one page works for every upload and preview that page can make.
+
+### Version history
+
+A journal-backed document keeps its past. Five routes list it, read one version, list the edits inside one, restore one and delete old history. Blok ships the data and the routes. Your app builds the history UI.
+
+A version is a point, the pair `(lineage, sequence)`. A lineage is one unbroken run of the journal. A reset, a first seed or the format migration starts a new one. Sequence 0 is the state the lineage started from. Store points in your own records, never positions in the list: the newest version keeps growing while people edit.
+
+| Route | Access | Answer |
+| --- | --- | --- |
+| `GET /sync/{doc}/history` | read | `200 { lineages, versions }` |
+| `GET /sync/{doc}/history/{lineage}/{sequence}` | read | `200 { time?, blocks, title?, icon?, page?, values? }` with `Blok-History-Lineage` and `Blok-History-Sequence` |
+| `GET /sync/{doc}/history/{lineage}/{sequence}/changes?since=` | read | `200 { changes, truncated? }` with `Blok-History-Lineage` and `Blok-History-Sequence` |
+| `POST /sync/{doc}/history/{lineage}/{sequence}/restore` | read and write | As `edit`: `204` with the new `Blok-Doc-Lineage` and `Blok-Doc-Sequence` |
+| `DELETE /sync/{doc}/history/{lineage}` | read and write | `204`; `404` for an unknown lineage; `409` for the current one |
+
+The list looks like this:
+
+```json
+{
+  "lineages": [{ "lineage": "…", "epoch": 2, "format": 2, "createdAt": 1760000000000, "current": true }],
+  "versions": [{ "lineage": "…", "sequence": 41, "startedAt": 1760000000000, "savedAt": 1760000300000, "actors": ["u1"] }]
+}
+```
+
+- Each lineage's baseline is a version at sequence 0.
+- The records after it are grouped by time. A new group starts after a gap of more than 2 minutes, or once a group spans 10 minutes. A group's `sequence` is its last record, and `actors` lists the distinct actor ids in the order they first appear.
+- `?group=1`, `?group=15` or `?group=60` sets both limits to that many minutes. A new group then starts after a gap of more than that window, or once a group spans it. Any other value answers 400, and so do an empty, signed or repeated `group`. The JSON shape does not change.
+- Versions come newest first.
+- Times are Unix milliseconds. An unknown time is `null`, and the point read leaves `time` out.
+- The point read sends the point's page title and icon as top-level `title` and `icon`, as your document endpoint gets them. Each is left out when the point has none.
+- It also sends the point's `page` and `values` maps as plain objects. Only plain JSON keys are listed, the same keys a restore copies. The `page` object never repeats `title` or `icon`. An empty map is left out.
+
+The point read's headers are deliberately not `Blok-Doc-*`. Those name the live head and feed `If-Match`. The point read and the changes read send no `ETag`. Both add `Blok-History-Lineage` and `Blok-History-Sequence` to `Access-Control-Expose-Headers` for an allowed origin. On the changes read they name the point in the path. Every answer from the history handlers sends `Cache-Control: no-store`. Guard refusals, 405 answers and preflights come from the route shell all routes share.
+
+The changes read lists the edits inside one version. Pass `since` as the sequence of the next older version in the list you show. Only your app knows which grouping that list uses. The answer covers the records after `since`, up to and including `sequence`, oldest first. Without `since` it starts after 0.
+
+```json
+{
+  "changes": [
+    {
+      "sequence": 12,
+      "committedAt": 1760000000000,
+      "actor": "u1",
+      "blocks": [
+        {
+          "id": "a",
+          "type": "paragraph",
+          "kind": "changed",
+          "before": { "id": "a", "type": "paragraph", "data": { "text": [{ "text": "one" }] } },
+          "after": { "id": "a", "type": "paragraph", "data": { "text": [{ "text": "two" }] } }
+        }
+      ]
+    },
+    { "sequence": 13, "committedAt": 1760000004000, "actor": null, "blocks": [], "page": ["title", "values.k"] }
+  ]
+}
+```
+
+- Each journal record gets one row, even one with no visible edit. Its `blocks` is then empty.
+- `actor` is always there. It is `null` when the record has none.
+- A block's `kind` is `added`, `removed`, `changed` or `moved`. `before` is left out for `added`, and `after` for `removed`. Blocks have the same shape as in the point read.
+- `changed` means the `type`, `data` or `tunes` differ. It wins over `moved`.
+- `moved` means a new parent, or a place outside the largest set of its siblings that kept their relative order. It is the same move test `diffOutputData` uses. A changed block still counts toward that order.
+- `page` lists the changed keys of the `page` map, such as `title` and `icon`. Then it lists changed tracked values as `values.<key>`. It is left out when nothing there changed.
+- One answer holds at most 200 rows and at most 4 MiB of rows. Past that, it holds the newest rows that fit and adds `"truncated": true`. The key is left out otherwise. The newest row always comes, even when it alone is larger.
+- To read older rows, ask again with the oldest row's `sequence` minus 1 in the path and the same `since`.
+- Sequence 0, or a `since` equal to the sequence, answers `{"changes":[]}`.
+
+Restore is a forward edit, not a rewind. It runs inside the room, through the same path as `edit`, so every open tab sees it and the old versions stay listed.
+
+- It needs a `Blok-Idempotency-Key`. A retry with the same key returns the first receipt. A missing or malformed key answers 400.
+- It takes an optional `If-Match`, checked as for `edit`. A malformed tag answers 400. A stale tag answers 412 and changes nothing, even when the point no longer exists.
+- A restore that changes nothing answers 204 at the current head.
+- A restore whose update would not fit one sync frame answers 413 and changes nothing. The limit is `CollabMaxMessageBytes`. On the built-in journal it is also never above that journal's 1 MiB update limit.
+- A planned change the converter refuses answers 422 and changes nothing.
+- A block whose `type` or `tunes` changed is removed and inserted again.
+- It also makes the `page` map (the built-in title and icon) and the `values` map (`history.track`) match the point. A key whose value differs is set to a copy. A key the point lacks is removed.
+- That map patch is part of the same edit. It lands in the same single journal record and counts toward the 413 limit.
+- A key whose value at the point is not plain JSON, such as a nested Yjs type, is left as it is.
+
+The history routes can also answer the statuses below. The list has no lineage or sequence in its path, so it never answers 404.
+
+| Status | When |
+| --- | --- |
+| 400 | The sequence is not an unsigned 64-bit whole number. Or the list's `group` is not 1, 15 or 60. Or the changes read's `since` is not a whole number, or is above the sequence. |
+| 403 | The document was purged. |
+| 404 | The lineage is unknown or is not 32 lowercase hex characters, or the sequence is past its durable head. |
+| 500 | A stored manifest, ledger or journal could not be decoded, on the list too. Or a replay failed, or the export after it. The server logs it. |
+| 501 | `history needs a journal that keeps it`: there is no journal, or your store does not keep history. |
+| 503 with `Retry-After` | The converter failed for a moment, as on `state`. |
+
+History needs a journal that keeps it. `--collab-journal` does. A store you register keeps history only if it also implements `ICollabOperationHistoryStore` (`Blok.Server.Collab`). The service finds it by a type check on your `ICollabOperationStore`, which does not change. The interface lists lineages, reads a baseline, streams record headers and records, and deletes a lineage. Its reads take no fence and no document lock, because a live room keeps writing while history is read. It also has `IsPurgedAsync`, which you must implement. It must answer without a lock, and it must still report a purge after a restart. Lineage values come from requests, so compare them and never build paths from them.
+
+History starts at this release. The built-in journal never stored the lineage, epoch and format of the generations it finished before, so it cannot list them. Its oldest listed lineage is the one current when this release first touches the document.
+
+Blok has no retention policy, and it never deletes history by itself. A lineage is kept whole or deleted whole. To trim, call `POST /sync/{doc}/reset`, then `DELETE` the lineage that was current before it. On the built-in journal, deleting the lineage just before the current one also gives up its fallback copy, which only matters after disk corruption.
 
 ## Rich text is segments
 
@@ -424,7 +608,7 @@ What the service requires of it:
 - **Cancellation belongs to the caller.** A store-side timeout or abort surfaces as some other exception, because the caller reads a cancellation it did not ask for as its own shutdown.
 - **Disposal releases the fence, unless it is already gone.** `DisposeAsync` lets another process open the document, and never throws because the fence was already lost; every method throws `ObjectDisposedException` afterwards. A session that HAS lost the fence releases nothing. The fence it would release now belongs to somebody else, so a `DisposeAsync` that unconditionally drops its lock row hands a third writer the document while the second is mid-write.
 
-A backend that is not .NET implements the wire protocol instead of this interface. `packages/server/protocol/blok-sync-v2.md` is a normative spec written so a server outside this repository can be built from it alone, and the frame vectors it pins live in `test/unit/server-conformance/fixtures/sync-frames.json`. This repository's conformance runner builds and drives the C# host only (`node scripts/test-server-conformance.mjs --target csharp`). Another backend runs those vectors in its own harness, along with the same durability scenarios: restart the process, fail the next append, inspect history.
+A backend that is not .NET implements the wire protocol instead of this interface. `packages/server/protocol/blok-sync-v2.md` is a normative spec written so a server outside this repository can be built from it alone, and the frame vectors it pins live in `test/unit/server-conformance/fixtures/sync-frames.json`. This repository's conformance runner builds and drives the C# host (`node scripts/test-server-conformance.mjs --target csharp`) and the Go host (`--target go`). Another backend runs those vectors in its own harness, along with the same durability scenarios: restart the process, fail the next append, inspect history.
 
 Stock `y-websocket` never offers `blok-sync.v2`, so it negotiates v1 and is compatible with the working-copy profile alone: ordinary y-protocol sync, no acknowledgement, no durability claim. On a journal-backed document a v1 write is still journaled before it is relayed; it earns no receipt. The same holds for any client that offers only v1.
 
@@ -548,7 +732,36 @@ dotnet format packages/server/dotnet/Blok.Server.slnx --verify-no-changes
 dotnet restore packages/server/dotnet/Blok.Server.slnx
 ```
 
-CI collects merged production coverage and requires at least 80% line and 80% branch coverage. It also runs the SDK analyzers with warnings as errors, and audits all direct and transitive NuGet packages. It scans committed secrets with Gitleaks, scans the server tree and built image with Trivy, and analyzes C# with CodeQL. Dependabot keeps NuGet, Docker, and GitHub Actions dependencies current.
+CI collects merged production coverage and requires at least 80% line and 80% branch coverage. It also runs the SDK analyzers with warnings as errors, and audits all direct and transitive NuGet packages. It scans committed secrets with Gitleaks, scans the server tree and built image with Trivy, and analyzes C# with CodeQL. Dependabot keeps NuGet, Go, Docker, and GitHub Actions dependencies current.
+
+The Go server in `packages/server/go` has its own CI checks:
+
+- `gofmt` must report no unformatted file.
+- `go vet` must pass.
+- `govulncheck` (pinned to v1.9.0) must find no reachable vulnerability.
+- `go test` must cover at least 80% of statements. Go measures statements only, so there is no Go branch floor.
+- Every conformance suite runs with `--target go`. `--target interop` checks that each server serves a collaboration directory the other wrote.
+- `node scripts/test-server-go-module.mjs` builds `test/fixtures/go-server-consumer` from the files git tracks in the module. The fixture mounts Blok under `/api/blok` behind its own auth, converts a document, and fills the collab seams.
+
+CodeQL analyzes the Go code in the weekly scan, not on every push.
+
+```bash
+cd packages/server/go
+gofmt -l .
+go vet ./...
+go test -p 2 ./...
+```
+
+## Go module and archives
+
+The release workflow ships the Go server in two forms. No release has shipped them yet.
+
+- **Module.** `yarn release X.Y.Z` also tags `packages/server/go/vX.Y.Z` on the release commit. Go reads a module in a subdirectory only from tags with that prefix. The module path is `github.com/JackUait/blok/packages/server/go/v2`. Import `blokserver` for the routes and `blokdocs` for the converter. Your own operation store and activity observer go in `Options.CollabOperationStore` and `Options.CollabActivityObserver`. Their types are in `blokserver/collabstore`. To put your own auth in front of the routes, use `Server.HandlerWithAuth(prefix, auth)`. It works like `RequireAuthorization()` on the C# group: health and CORS preflights stay open.
+- **Archives.** The GitHub release gets `blok-server-go_<os>_<arch>` for macOS, Linux and Windows, on amd64 and arm64, with `checksums-go.txt`. They are built with cgo off, so they are static. The release starts the Linux amd64 one on Alpine before it uploads.
+
+The binary reports its release version on `/health`. A local `go build` reports `dev`.
+
+These names never overlap the C# archives or `checksums.txt`. The npm wrapper downloads only the C# archives, and a test fails if it ever names a Go one.
 
 ## Docs
 

package/dist/ticket.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let node_crypto = require("node:crypto");
-//#region src/ticket.ts
+// src/ticket.ts
 /** Must match BlokTicket.MinimumSecretLength (C#), the floor BlokServerOptions.Validate enforces, or the service refuses to start. */
 var MIN_SECRET_LENGTH = 32;
 var DEFAULT_TTL_SECONDS = 300;
@@ -36,5 +36,4 @@ function blokTicket(secret, claims) {
 function b64(value) {
 	return Buffer.from(value, "utf-8").toString("base64url");
 }
-//#endregion
 exports.blokTicket = blokTicket;

package/dist/ticket.mjs

@@ -1,5 +1,5 @@
 import { createHmac } from "node:crypto";
-//#region src/ticket.ts
+// src/ticket.ts
 /** Must match BlokTicket.MinimumSecretLength (C#), the floor BlokServerOptions.Validate enforces, or the service refuses to start. */
 var MIN_SECRET_LENGTH = 32;
 var DEFAULT_TTL_SECONDS = 300;
@@ -35,5 +35,4 @@ function blokTicket(secret, claims) {
 function b64(value) {
 	return Buffer.from(value, "utf-8").toString("base64url");
 }
-//#endregion
 export { blokTicket };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bloklabs/server",
-  "version": "1.16.0",
+  "version": "2.0.0",
   "description": "Blok server delivery for ASP.NET Core, npm, and Docker — shared C# routes for file uploads and link previews.",
   "license": "Apache-2.0",
   "author": "JackUait",