@bloklabs/server 1.11.0 → 1.13.0

package/README.md

@@ -1,21 +1,183 @@
 # @bloklabs/server
 
-A small Go sidecar for [Blok](https://blokeditor.com). It answers the two requests a rich-text editor cannot make from the browser — storing an uploaded file, and reading the title/description/image of a pasted link — so you do not write a backend for either.
+Blok's shared C# server handles file uploads, link previews and live collaboration, and converts saved documents. Use it inside an ASP.NET Core app, or run the same routes as a standalone npm binary or Docker image.
 
-It stores no documents. There is no database, and nothing here is a hosted service you depend on: you run it.
+Documents stay yours: saving and loading them is a small endpoint in your own app, and that endpoint remains the record. With live collaboration on, the service keeps only a working copy of each open document, in storage you point it at, and writes what people type back to your endpoint every few seconds. The packages include no database-block or MySQL integration; those follow this delivery migration.
 
-## Run it
+## ASP.NET Core
+
+Install the public integration package. NuGet brings in `Blok.Server` transitively.
+
+```bash
+dotnet add package Blok.Server.AspNetCore
+```
+
+Register the services, use your application's authorization policy, and map the routes under one prefix:
+
+```csharp
+using Blok.Server.AspNetCore;
+
+builder.Services.AddBlokServer(options =>
+{
+  options.StorageDirectory = "./blok-uploads";
+  options.PublicUrl = "https://uploads.example.com/files";
+  options.UnfurlDisabled = false;
+});
+
+var app = builder.Build();
+
+app.MapBlokServer("/api/blok").RequireAuthorization();
+app.Run();
+```
+
+The mapped group uses your ASP.NET Core authorization policy for upload and unfurl routes. Health and validated CORS preflight remain anonymous.
+
+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.
+
+## Convert documents
+
+`Blok.Server` carries Blok's own serializer as an embedded JavaScript bundle and runs it in this process, so a document converts through the editor's implementation rather than a port of it. A port has to be taught every block Blok gains and silently drops the ones nobody remembered.
+
+Conversion needs no storage, no outbound access and no route, so it registers on its own:
+
+```csharp
+using Blok.Server.Documents;
+
+builder.Services.AddBlokDocuments();
+```
+
+`AddBlokServer` already includes it. Outside dependency injection, `BlokDocuments.Create()` returns the same thing.
+
+```csharp
+public sealed class ArticleExport(IBlokDocumentConverter blok, ILogger<ArticleExport> logger)
+{
+  public async Task<string> ToMarkdownAsync(string documentJson, CancellationToken ct)
+  {
+    var conversion = await blok.ToMarkdownAsync(documentJson, ct);
+
+    foreach (var warning in conversion.Warnings)
+    {
+      // e.g. construct "callout", action "degraded", detail "rendered as a blockquote…"
+      logger.LogInformation("{Construct} {Action}: {Detail}", warning.Construct, warning.Action, warning.Detail);
+    }
+
+    return conversion.Markdown;
+  }
+}
+```
+
+| Method | Returns |
+|--------|---------|
+| `ToMarkdownAsync` | the Markdown, plus every construct Markdown could not carry |
+| `ToHtmlAsync` | the document's HTML |
+| `ToPlainTextAsync` | the document's readable text |
+| `FromMarkdownAsync` | the saved document, plus what Markdown could not carry into it |
+| `ExtractTextsAsync` / `InjectTextsAsync` | the document's translatable strings, and the document with them put back |
+| `GetVersionAsync` | the `version` the editor stamps into a saved document |
+| `GetSchemaAsync` | the saved format as JSON Schema (draft 2020-12) |
+
+### Translate a document without handing a model its JSON
+
+A model asked to translate a document's JSON breaks the structure — it drops
+ids, reorders blocks, invents fields. Take the strings out instead, translate
+the list, and put it back; the model never sees the structure, so it cannot
+break it.
+
+```csharp
+var texts = await blok.ExtractTextsAsync(documentJson, cancellationToken: ct);
+var translated = await TranslateAsync(texts, ct);       // your own model call
+var document = await blok.InjectTextsAsync(documentJson, translated, cancellationToken: ct);
+```
+
+The list is in document order, skips empty values, and holds no URLs — nor a
+file's name, which is what the reader downloads rather than prose. Code blocks
+are out by default; pass `includeCode: true` to both calls if you want them.
+A list whose length does not match the document is an `ArgumentException`
+rather than a silently misplaced translation, and a block too malformed to read
+is carried through untouched — the result of `InjectTextsAsync` is what you
+store.
+
+### Stamp the version the editor stamps
+
+`version` in a saved document is whatever wrote it. A service writing documents
+outside the browser should ask rather than invent a number, or the same column
+ends up holding two different answers:
+
+```csharp
+var document = new JsonObject
+{
+  ["time"] = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds(),
+  ["blocks"] = blocks,
+  ["version"] = await blok.GetVersionAsync(ct),
+};
+```
+
+Markdown cannot express every block — a callout becomes a blockquote, columns flatten, a spacer disappears — so both directions report what changed. A caller handing the result to something that cannot ask a follow-up question, an export or a model, should read that report rather than assume the round trip was lossless.
+
+An instance holds a pool of engines and is expensive to construct — every engine parses the embedded bundle, about a second in total — so register one for the lifetime of the process. `AddBlokDocuments` builds it at startup rather than during the first request; pass `warmUp: false` where a host starts often and converts rarely, such as a test host. The pool size bounds how many documents convert at once; further callers wait. A conversion is bounded by a timeout and a recursion limit, so a pathological document fails rather than wedging the process.
+
+## Standalone
+
+Run the self-contained host through npm:
 
 ```bash
 npx @bloklabs/server --listen 127.0.0.1:4000
 ```
 
-The npm package is a wrapper. On first run it downloads the binary for your platform from the matching GitHub release, checks it against the release's `checksums.txt`, and caches it. If your network blocks that download, the container image is the same build:
+The npm package is a small wrapper. On first run it downloads the C# host for macOS, Windows or Linux (including Alpine/musl), verifies it against `checksums.txt`, and caches it. Both x64 and arm64 are published. The host is fully managed: every archive and the NuGet package are built from managed code alone, with no native library, so there is no extraction directory and nothing to set for a service account with no home.
+
+The same host is available at the existing image name. In proxy mode it must stay on loopback, so this example uses the host network. The named volume keeps uploads in the image's writable `/data` directory:
 
 ```bash
-docker run -p 4000:4000 ghcr.io/jackuait/blok-server --listen 0.0.0.0:4000
+docker run --rm \
+  --network host \
+  --mount type=volume,source=blok-server-data,target=/data \
+  ghcr.io/jackuait/blok-server \
+  --listen 127.0.0.1:4000 \
+  --auth proxy \
+  --storage-dir /data \
+  --public-url https://uploads.example.com/files
 ```
 
+For an internet-facing deployment, use ticket authentication and publish the container port only on loopback for the local reverse proxy:
+
+```bash
+docker run --rm \
+  -p 127.0.0.1:4000:4000 \
+  --mount type=volume,source=blok-server-data,target=/data \
+  -e BLOK_SECRET \
+  ghcr.io/jackuait/blok-server \
+  --listen 0.0.0.0:4000 \
+  --auth ticket \
+  --allow-origin https://myapp.com \
+  --storage-dir /data \
+  --public-url https://uploads.example.com/files
+```
+
+Set `BLOK_SECRET` to a random value of at least 32 characters. Put the service behind a reverse proxy or hosting platform that terminates TLS before forwarding plain HTTP to it; the host does not manage certificates. The process refuses unsafe public configurations instead of starting with a warning.
+
+The same service, with live collaboration:
+
+```bash
+docker run \
+  -p 127.0.0.1:4000:4000 \
+  --mount type=volume,source=blok-server-data,target=/data \
+  --mount type=volume,source=blok-collab,target=/collab \
+  -e BLOK_SECRET \
+  -e BLOK_DOC_ENDPOINT_AUTH \
+  ghcr.io/jackuait/blok-server \
+  --listen 0.0.0.0:4000 \
+  --auth ticket \
+  --allow-origin https://myapp.com \
+  --storage-dir /data \
+  --public-url https://blok.myapp.com/files \
+  --collab \
+  --collab-dir /collab \
+  --doc-endpoint https://myapp.com/api/documents
+```
+
+`--collab` turns the sync routes on. `--doc-endpoint` names the routes in your own app 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, and 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 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()`.
+
 ## Point the editor at it
 
 ```ts
@@ -23,43 +185,74 @@ import { Blok } from '@bloklabs/core';
 
 new Blok({
   holder: 'editor',
-  uploader: {
-    async uploadByFile(file) {
-      const body = new FormData();
+  server: '/api/blok',
+});
+```
+
+One key fills in the uploader and the link-preview endpoint. Anything you set yourself wins, so uploading into your own storage while keeping previews here needs no extra wiring.
+
+The standalone host uses routes at the root. An ASP.NET Core app uses the prefix passed to `MapBlokServer`.
+
+## Access passes
+
+A standalone host cannot see who your user is, so your own backend vouches for them with a short-lived pass:
+
+```ts
+import { blokTicket } from '@bloklabs/server/ticket';
+
+export async function GET() {
+  const session = await getSession();
 
-      body.append('file', file);
+  if (!session) {
+    return new Response('Not signed in', { status: 401 });
+  }
 
-      const res = await fetch('http://127.0.0.1:4000/upload', { method: 'POST', body });
+  return Response.json({
+    ticket: blokTicket(process.env.BLOK_SECRET, { user: session.userId, write: true }),
+  });
+}
+```
 
-      return res.json();
-    },
-  },
+```ts
+new Blok({
+  holder: 'editor',
+  server: 'https://blok.myapp.com',
+  ticket: '/api/blok-ticket',
 });
 ```
 
-The response shapes match what Blok's own parsers already expect, so nothing on the editor side needs configuring beyond the URL.
+The editor caches the pass and replaces it ahead of expiry, and uploads and link previews share the same one.
+
+A pass is a plain HS256 JWT carrying `user`, `doc`, `write` and `exp`, signed with the secret the service runs with (at least 32 characters). Any backend can mint one with its own JWT library — `blokTicket` exists so a JavaScript one does not have to. Routes running inside your own ASP.NET app need none of this: they already know who the caller is.
 
 ## Routes
 
 | Route | What it does |
 | --- | --- |
-| `GET /health` | Liveness plus the running version |
-| `GET /unfurl?url=…` | Title, description and image for a pasted link |
-| `POST /upload` | Stores an uploaded file, returns where it landed |
-| `POST /upload-by-url` | Fetches a remote URL server-side and re-hosts it |
+| `GET /health` | Reports liveness and the running version |
+| `GET /unfurl?url=…` | Reads title, description, and image metadata |
+| `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, and reaches every open tab |
+
+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.
 
-Both routes that fetch a URL the browser supplied go through one SSRF-guarded HTTP client, so a pasted `http://169.254.169.254/…` cannot reach your cloud metadata endpoint.
+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` 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` and its `edit` are refused when the pass names no document or a different one. 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.
 
-## Access modes
+## Quality gates
 
-`--auth` picks who may call the service, and the process refuses to start on a combination that would leave it open:
+The .NET solution keeps three test layers: `Blok.Server.Tests` for core behavior, `Blok.Server.AspNetCore.Tests` for in-process integration, and `Blok.Server.Host.Tests` for real-process end-to-end behavior. CI also runs the cross-runtime conformance and package smoke tests.
 
-- `none` — no check, and therefore only allowed to bind loopback.
-- `proxy` — trusts every caller, for when something in front of it already authenticated them; loopback only for the same reason.
-- `ticket` — each request carries a short-lived pass your app signs with the shared secret. The only mode allowed to bind a public address.
+```bash
+dotnet test packages/server/dotnet/Blok.Server.slnx --configuration Release
+dotnet format packages/server/dotnet/Blok.Server.slnx --verify-no-changes
+dotnet restore packages/server/dotnet/Blok.Server.slnx
+```
 
-Storage is a local directory by default (`--storage-dir`), or any S3-compatible bucket via `--s3-bucket` and friends. Credentials are read from `BLOK_S3_ACCESS_KEY` / `BLOK_S3_SECRET_KEY` — never from flags, which land in process listings.
+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, audits all direct and transitive NuGet packages, 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.
 
 ## Docs
 
-Full flag reference and deployment notes: [https://blokeditor.com/docs](https://blokeditor.com/docs)
+Full configuration and deployment guidance: [https://blokeditor.com/docs](https://blokeditor.com/docs)

package/bin/blok-server.mjs

@@ -1,17 +1,14 @@
 #!/usr/bin/env node
 /**
- * npm wrapper for the blok-server Go binary.
+ * npm wrapper for the published blok-server binary.
  *
- * The package ships no binary. On first run it resolves the archive goreleaser
- * published for this platform on the GitHub release matching this package's
- * version, verifies it against that release's checksums.txt, unpacks it into a
- * cache directory, and execs it. Later runs go straight to the cached binary.
+ * The package ships no binary. On first run it resolves the archive published
+ * for this platform on the matching GitHub release, verifies checksums.txt,
+ * unpacks it into a cache directory, and runs it. Later runs use the cache.
  *
- * The version is the family version, not a server version: every release moves
- * it whether or not the Go sources changed, which is why .github/workflows/
- * release-server.yml publishes archives on EVERY tag and skips only the image.
+ * The release and npm package use the same family version.
  */
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { homedir, tmpdir } from 'node:os';
@@ -21,31 +18,54 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 const REPO = 'https://github.com/JackUait/blok';
 const IMAGE = 'ghcr.io/jackuait/blok-server';
 const CHECKSUMS_FILE = 'checksums.txt';
+const DOWNLOAD_TIMEOUT_MS = 30_000;
 
 const here = dirname(fileURLToPath(import.meta.url));
 
-/** Mirrors the goos/goarch matrix in .goreleaser.yaml. */
 const PLATFORMS = { darwin: 'darwin', linux: 'linux', win32: 'windows' };
 const ARCHITECTURES = { x64: 'amd64', arm64: 'arm64' };
+const RUNTIMES = {
+  darwin: { x64: 'osx-x64', arm64: 'osx-arm64' },
+  linux: { x64: 'linux-x64', arm64: 'linux-arm64' },
+  win32: { x64: 'win-x64', arm64: 'win-arm64' },
+};
+
+/**
+ * @param {{ header?: { glibcVersionRuntime?: string } }} [report] Node process report.
+ * @returns {'glibc' | 'musl'} Linux C library.
+ */
+export function detectLinuxLibc(
+  report = process.report === undefined ? undefined : process.report.getReport(),
+) {
+  return report?.header?.glibcVersionRuntime === undefined ? 'musl' : 'glibc';
+}
 
 /**
  * @param {string} platform - process.platform
  * @param {string} arch - process.arch
- * @returns {{ os: string, arch: string, archive: string, binary: string } | null}
+ * @param {'glibc' | 'musl'} [libc] Linux C library.
+ * @returns {{ os: string, arch: string, rid: string, archive: string, binary: string } | null}
  */
-export function resolveTarget(platform, arch) {
+export function resolveTarget(platform, arch, libc = 'glibc') {
   const os = PLATFORMS[platform];
-  const goarch = ARCHITECTURES[arch];
+  const archiveArch = ARCHITECTURES[arch];
+  const rid = platform === 'linux' && libc === 'musl'
+    ? RUNTIMES.linux?.[arch]?.replace('linux-', 'linux-musl-')
+    : RUNTIMES[platform]?.[arch];
 
-  if (os === undefined || goarch === undefined) {
+  if (os === undefined || archiveArch === undefined || rid === undefined) {
     return null;
   }
 
-  // Must match archives.name_template + format_overrides in .goreleaser.yaml.
+  const archiveOs = platform === 'linux' && libc === 'musl'
+    ? 'linux_musl'
+    : os;
+
   return {
     os,
-    arch: goarch,
-    archive: `blok-server_${os}_${goarch}.${os === 'windows' ? 'zip' : 'tar.gz'}`,
+    arch: archiveArch,
+    rid,
+    archive: `blok-server_${archiveOs}_${archiveArch}.${os === 'windows' ? 'zip' : 'tar.gz'}`,
     binary: os === 'windows' ? 'blok-server.exe' : 'blok-server',
   };
 }
@@ -57,8 +77,8 @@ export function supportedTargets() {
 }
 
 /**
- * Read one asset's expected digest out of a goreleaser checksums file, whose
- * lines are `<sha256><two spaces><filename>`.
+ * Read one asset's expected digest from a release checksums file, whose lines
+ * are `<sha256><two spaces><filename>`.
  *
  * @param {string} contents - checksums.txt body
  * @param {string} assetName - the archive filename to look up
@@ -101,40 +121,55 @@ export function cacheRoot(env, platform) {
 }
 
 /**
- * First of the candidate roots that actually accepts a write. A cache that
- * cannot be written is not an error yet — the temp directory is a fine second
- * home for a single run — so this only throws when nothing is writable.
+ * Use the persistent cache when it is writable. Otherwise make a private,
+ * per-run directory so another local user cannot predict the launcher path.
  *
- * @param {string[]} candidates
- * @returns {string}
+ * @param {string} persistentRoot
+ * @param {string} temporaryParent
+ * @returns {{ root: string, temporary: boolean }}
  */
-function firstWritable(candidates) {
-  const failures = [];
+export function prepareInstallRoot(persistentRoot, temporaryParent = tmpdir()) {
+  let persistentFailure;
 
-  for (const candidate of candidates) {
-    try {
-      mkdirSync(candidate, { recursive: true });
+  try {
+    mkdirSync(persistentRoot, { recursive: true });
 
-      const probe = join(candidate, `.write-probe-${process.pid}`);
+    const probe = mkdtempSync(join(persistentRoot, '.write-probe-'));
 
-      writeFileSync(probe, '');
-      rmSync(probe, { force: true });
+    rmSync(probe, { recursive: true, force: true });
 
-      return candidate;
-    } catch (error) {
-      failures.push(`${candidate} (${error.message})`);
-    }
+    return { root: persistentRoot, temporary: false };
+  } catch (error) {
+    persistentFailure = `${persistentRoot} (${error.message})`;
   }
 
-  throw new Error(`no writable cache directory: ${failures.join('; ')}`);
+  let temporaryRoot;
+
+  try {
+    temporaryRoot = mkdtempSync(join(temporaryParent, 'blok-server-'));
+    chmodSync(temporaryRoot, 0o700);
+
+    return { root: temporaryRoot, temporary: true };
+  } catch (error) {
+    if (temporaryRoot !== undefined) {
+      rmSync(temporaryRoot, { recursive: true, force: true });
+    }
+
+    throw new Error(
+      `no writable cache directory: ${persistentFailure}; ${temporaryParent} (${error.message})`,
+    );
+  }
 }
 
 /**
  * @param {string} url
+ * @param {typeof fetch} fetchImpl
  * @returns {Promise<Buffer>}
  */
-async function download(url) {
-  const response = await fetch(url);
+async function download(url, fetchImpl) {
+  const response = await fetchImpl(url, {
+    signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
+  });
 
   if (!response.ok) {
     throw new Error(`GET ${url} → ${response.status} ${response.statusText}`);
@@ -151,13 +186,19 @@ async function download(url) {
  * any point leaves a scratch directory, never a truncated binary at the path the
  * next run would execute.
  *
- * @param {{ version: string, target: ReturnType<typeof resolveTarget>, destination: string }} opts
+ * @param {{
+ *   version: string,
+ *   target: NonNullable<ReturnType<typeof resolveTarget>>,
+ *   destination: string,
+ *   fetchImpl?: typeof fetch,
+ * }} opts
  */
-async function fetchBinary({ version, target, destination }) {
+export async function installBinary({ version, target, destination, fetchImpl = fetch }) {
   const base = `${REPO}/releases/download/v${version}`;
-  // A 404 here means an unsigned download, so it aborts the run rather than
-  // falling through to "verification unavailable, running it anyway".
-  const checksums = (await download(`${base}/${CHECKSUMS_FILE}`)).toString('utf-8');
+  // A 404 here means an unsigned download, so the run must stop.
+  const checksums = (
+    await download(`${base}/${CHECKSUMS_FILE}`, fetchImpl)
+  ).toString('utf-8');
   const expected = checksumFor(checksums, target.archive);
 
   if (expected === null) {
@@ -167,7 +208,7 @@ async function fetchBinary({ version, target, destination }) {
   const scratch = mkdtempSync(join(dirname(destination), '.download-'));
 
   try {
-    const archive = await download(`${base}/${target.archive}`);
+    const archive = await download(`${base}/${target.archive}`, fetchImpl);
     const actual = createHash('sha256').update(archive).digest('hex');
 
     if (actual !== expected) {
@@ -212,6 +253,38 @@ async function fetchBinary({ version, target, destination }) {
   }
 }
 
+/**
+ * Run the native host while keeping the npm wrapper responsive to termination.
+ *
+ * @param {string} binary
+ * @param {string[]} args
+ * @returns {Promise<{ code: number | null, signal: NodeJS.Signals | null }>}
+ */
+export function runBinary(binary, args) {
+  const child = spawn(binary, args, { stdio: 'inherit' });
+
+  return new Promise((resolvePromise, reject) => {
+    const forwardSigint = () => child.kill('SIGINT');
+    const forwardSigterm = () => child.kill('SIGTERM');
+    const removeSignalHandlers = () => {
+      process.off('SIGINT', forwardSigint);
+      process.off('SIGTERM', forwardSigterm);
+    };
+
+    process.on('SIGINT', forwardSigint);
+    process.on('SIGTERM', forwardSigterm);
+
+    child.once('error', (error) => {
+      removeSignalHandlers();
+      reject(error);
+    });
+    child.once('exit', (code, signal) => {
+      removeSignalHandlers();
+      resolvePromise({ code, signal });
+    });
+  });
+}
+
 /**
  * @param {string} version
  * @param {string} reason
@@ -222,9 +295,7 @@ export function fallbackMessage(version, reason) {
     `blok-server: ${reason}`,
     '',
     'The same build is published as a container image — run that instead:',
-    // The service defaults to loopback, which nothing outside the container can
-    // reach, so the published port needs an explicit bind address to match.
-    `  docker run -p 4000:4000 ${IMAGE}:${version} --listen 0.0.0.0:4000`,
+    `  docker run --network host ${IMAGE}:${version} --listen 127.0.0.1:4000 --auth proxy`,
     '',
     `Or download it by hand: ${REPO}/releases/tag/v${version}`,
   ].join('\n');
@@ -232,7 +303,8 @@ export function fallbackMessage(version, reason) {
 
 async function main() {
   const { version } = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf-8'));
-  const target = resolveTarget(process.platform, process.arch);
+  const libc = process.platform === 'linux' ? detectLinuxLibc() : 'glibc';
+  const target = resolveTarget(process.platform, process.arch, libc);
 
   if (target === null) {
     console.error(fallbackMessage(
@@ -243,31 +315,47 @@ async function main() {
   }
 
   let binary;
+  let temporaryRoot;
 
   try {
-    const root = firstWritable([
-      join(cacheRoot(process.env, process.platform), version),
-      join(tmpdir(), 'blok-server', version),
-    ]);
+    const prepared = prepareInstallRoot(
+      join(cacheRoot(process.env, process.platform), version, target.rid),
+    );
 
-    binary = join(root, target.binary);
+    binary = join(prepared.root, target.binary);
+    temporaryRoot = prepared.temporary ? prepared.root : undefined;
 
     if (!existsSync(binary)) {
-      await fetchBinary({ version, target, destination: binary });
+      await installBinary({ version, target, destination: binary });
     }
   } catch (error) {
+    if (temporaryRoot !== undefined) {
+      rmSync(temporaryRoot, { recursive: true, force: true });
+    }
+
     console.error(fallbackMessage(version, error.message));
     process.exit(1);
   }
 
-  const result = spawnSync(binary, process.argv.slice(2), { stdio: 'inherit' });
+  let result;
 
-  if (result.error) {
-    console.error(fallbackMessage(version, `could not start ${binary}: ${result.error.message}`));
+  try {
+    result = await runBinary(binary, process.argv.slice(2));
+  } catch (error) {
+    console.error(fallbackMessage(version, `could not start ${binary}: ${error.message}`));
     process.exit(1);
+  } finally {
+    if (temporaryRoot !== undefined) {
+      rmSync(temporaryRoot, { recursive: true, force: true });
+    }
+  }
+
+  if (result.signal !== null) {
+    process.kill(process.pid, result.signal);
+    return;
   }
 
-  process.exit(result.status ?? 1);
+  process.exit(result.code ?? 1);
 }
 
 // Importing this file (the unit tests do) must not start a download.

package/dist/ticket.cjs

@@ -0,0 +1,40 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let node_crypto = require("node:crypto");
+//#region src/ticket.ts
+/** Must match the floor BlokServerOptions.Validate enforces, or the service refuses to start. */
+var MIN_SECRET_LENGTH = 32;
+var DEFAULT_TTL_SECONDS = 300;
+/**
+* Byte-exact, never negotiated: the service compares the ENCODED header segment
+* against a hard-coded constant, ordinally. Reordering these two keys, or adding
+* a space, is rejected — see the noncanonicalHeaderTicket conformance fixture.
+*/
+var HEADER = "{\"alg\":\"HS256\",\"typ\":\"JWT\"}";
+/**
+* Mints an access pass for one of your users, in your own backend.
+*
+* Not a Blok concept: it is a plain HS256 JWT. Any language can produce the
+* same thing with its own JWT library — this exists so a JavaScript backend
+* does not have to.
+* @param secret - the same secret the service runs with (BLOK_SECRET)
+* @param claims - who the pass is for and how long it lives
+*/
+function blokTicket(secret, claims) {
+	if (secret.length < MIN_SECRET_LENGTH) throw new Error(`blokTicket: the secret must be at least ${MIN_SECRET_LENGTH} characters`);
+	const payload = {
+		user: claims.user,
+		...claims.doc === void 0 ? {} : { doc: claims.doc },
+		write: claims.write ?? false,
+		exp: Math.floor(Date.now() / 1e3) + (claims.ttlSeconds ?? DEFAULT_TTL_SECONDS)
+	};
+	const signing = `${b64(HEADER)}.${b64(JSON.stringify(payload))}`;
+	return `${signing}.${(0, node_crypto.createHmac)("sha256", secret).update(signing).digest("base64url")}`;
+}
+/**
+* @param value - text to encode
+*/
+function b64(value) {
+	return Buffer.from(value, "utf-8").toString("base64url");
+}
+//#endregion
+exports.blokTicket = blokTicket;

package/dist/ticket.mjs

@@ -0,0 +1,39 @@
+import { createHmac } from "node:crypto";
+//#region src/ticket.ts
+/** Must match the floor BlokServerOptions.Validate enforces, or the service refuses to start. */
+var MIN_SECRET_LENGTH = 32;
+var DEFAULT_TTL_SECONDS = 300;
+/**
+* Byte-exact, never negotiated: the service compares the ENCODED header segment
+* against a hard-coded constant, ordinally. Reordering these two keys, or adding
+* a space, is rejected — see the noncanonicalHeaderTicket conformance fixture.
+*/
+var HEADER = "{\"alg\":\"HS256\",\"typ\":\"JWT\"}";
+/**
+* Mints an access pass for one of your users, in your own backend.
+*
+* Not a Blok concept: it is a plain HS256 JWT. Any language can produce the
+* same thing with its own JWT library — this exists so a JavaScript backend
+* does not have to.
+* @param secret - the same secret the service runs with (BLOK_SECRET)
+* @param claims - who the pass is for and how long it lives
+*/
+function blokTicket(secret, claims) {
+	if (secret.length < MIN_SECRET_LENGTH) throw new Error(`blokTicket: the secret must be at least ${MIN_SECRET_LENGTH} characters`);
+	const payload = {
+		user: claims.user,
+		...claims.doc === void 0 ? {} : { doc: claims.doc },
+		write: claims.write ?? false,
+		exp: Math.floor(Date.now() / 1e3) + (claims.ttlSeconds ?? DEFAULT_TTL_SECONDS)
+	};
+	const signing = `${b64(HEADER)}.${b64(JSON.stringify(payload))}`;
+	return `${signing}.${createHmac("sha256", secret).update(signing).digest("base64url")}`;
+}
+/**
+* @param value - text to encode
+*/
+function b64(value) {
+	return Buffer.from(value, "utf-8").toString("base64url");
+}
+//#endregion
+export { blokTicket };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bloklabs/server",
-  "version": "1.11.0",
-  "description": "Blok backend service — a small Go sidecar that handles file uploads and link previews, so you write no backend code for either.",
+  "version": "1.13.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",
   "homepage": "https://blokeditor.com",
@@ -26,16 +26,32 @@
     "sidecar",
     "ssrf"
   ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    "./ticket": {
+      "types": "./types/index.d.ts",
+      "import": "./dist/ticket.mjs",
+      "require": "./dist/ticket.cjs"
+    },
+    "./package.json": "./package.json"
+  },
   "bin": {
     "blok-server": "bin/blok-server.mjs"
   },
   "files": [
-    "bin"
+    "bin",
+    "dist",
+    "types"
   ],
   "engines": {
     "node": "^20.19.0 || ^22.13.0 || >=24.0.0"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "yarn run -T vite build --mode production",
+    "test": "yarn run -T vitest run"
   }
 }

package/types/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Public types for `@bloklabs/server/ticket`.
+ *
+ * Hand-authored, not generated: a published `.d.ts` may not reach outside its
+ * own tarball, so it cannot import from `src/`. Keep it in step with
+ * `src/ticket.ts` — `packages/server/src/ticket.test.ts` pins the runtime
+ * behaviour, and the shape below is the whole public surface.
+ */
+
+export interface BlokTicketClaims {
+  /** Your own user id. The service stores it but never interprets it. */
+  user: string;
+  /**
+   * Scope the pass to one document for sync (collaboration) access. The HTTP
+   * upload and unfurl routes do not read it — those stay user-scoped.
+   */
+  doc?: string;
+  /** Whether the holder may write. Defaults to false. */
+  write?: boolean;
+  /**
+   * Lifetime in seconds. Defaults to 300 — short on purpose. A collaboration
+   * pass outlives its handshake (verified at connect only), so ~1800 is a
+   * reasonable ceiling there.
+   */
+  ttlSeconds?: number;
+}
+
+/**
+ * Mints an access pass for one of your users, in your own backend.
+ *
+ * Not a Blok concept: it is a plain HS256 JWT. Any language can produce the
+ * same thing with its own JWT library — this exists so a JavaScript backend
+ * does not have to.
+ * @param secret - the same secret the service runs with (BLOK_SECRET)
+ * @param claims - who the pass is for and how long it lives
+ */
+export declare function blokTicket(secret: string, claims: BlokTicketClaims): string;