@bloklabs/server 1.12.0 → 1.13.0

package/README.md

@@ -1,8 +1,8 @@
 # @bloklabs/server
 
-Blok's shared C# server handles file uploads and link previews. Use it inside an ASP.NET Core app, or run the same routes as a standalone npm binary or Docker image.
+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.
 
-The current packages store no documents and include no database-block or MySQL integration. Those features follow this delivery migration.
+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.
 
 ## ASP.NET Core
 
@@ -17,14 +17,12 @@ Register the services, use your application's authorization policy, and map the
 ```csharp
 using Blok.Server.AspNetCore;
 
-builder.Services
-  .AddBlokServer(options =>
-  {
-    options.StorageDirectory = "./blok-uploads";
-    options.PublicUrl = "https://uploads.example.com/files";
-    options.UnfurlDisabled = false;
-  })
-  .UseAuthorization<MyBlokAuthorization>();
+builder.Services.AddBlokServer(options =>
+{
+  options.StorageDirectory = "./blok-uploads";
+  options.PublicUrl = "https://uploads.example.com/files";
+  options.UnfurlDisabled = false;
+});
 
 var app = builder.Build();
 
@@ -32,10 +30,92 @@ app.MapBlokServer("/api/blok").RequireAuthorization();
 app.Run();
 ```
 
-The mapped group uses your ASP.NET Core authorization policy for the current upload and unfurl routes. Health and validated CORS preflight remain anonymous. `IBlokAuthorization` is the document/database permission seam for later document routes; it is not called for uploads or unfurling.
+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:
@@ -44,17 +124,59 @@ Run the self-contained host through npm:
 npx @bloklabs/server --listen 127.0.0.1:4000
 ```
 
-The npm package is a small wrapper. On first run it downloads the C# host for your platform from the matching GitHub release, verifies it against `checksums.txt`, and caches it.
+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. This loopback example uses the host network so the service is not exposed directly to the internet:
+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 --network host ghcr.io/jackuait/blok-server \
+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
+  --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
 ```
 
-For an internet-facing deployment, use `--auth ticket`, set `BLOK_SECRET`, and provide `--allow-origin`. The process refuses unsafe public configurations instead of starting with a warning.
+`--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
 
@@ -63,24 +185,45 @@ 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
 
-      body.append('file', file);
+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';
 
-      const response = await fetch('/api/blok/upload', {
-        method: 'POST',
-        body,
-      });
+export async function GET() {
+  const session = await getSession();
 
-      return response.json();
-    },
-  },
+  if (!session) {
+    return new Response('Not signed in', { status: 401 });
+  }
+
+  return Response.json({
+    ticket: blokTicket(process.env.BLOK_SECRET, { user: session.userId, write: true }),
+  });
+}
+```
+
+```ts
+new Blok({
+  holder: 'editor',
+  server: 'https://blok.myapp.com',
+  ticket: '/api/blok-ticket',
 });
 ```
 
-The standalone host uses routes at the root. An ASP.NET Core app uses the prefix passed to `MapBlokServer`.
+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
 
@@ -89,9 +232,26 @@ The standalone host uses routes at the root. An ASP.NET Core app uses the prefix
 | `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 |
+| `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.
+
+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.
+
+## Quality gates
+
+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.
+
+```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
+```
 
-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.
+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
 

package/bin/blok-server.mjs

@@ -4,11 +4,11 @@
  *
  * 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 execs it. Later runs use the cache.
+ * unpacks it into a cache directory, and runs it. Later runs use the cache.
  *
  * 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';
@@ -18,6 +18,7 @@ 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));
 
@@ -29,25 +30,42 @@ const RUNTIMES = {
   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
+ * @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 archiveArch = ARCHITECTURES[arch];
-  const rid = RUNTIMES[platform]?.[arch];
+  const rid = platform === 'linux' && libc === 'musl'
+    ? RUNTIMES.linux?.[arch]?.replace('linux-', 'linux-musl-')
+    : RUNTIMES[platform]?.[arch];
 
   if (os === undefined || archiveArch === undefined || rid === undefined) {
     return null;
   }
 
+  const archiveOs = platform === 'linux' && libc === 'musl'
+    ? 'linux_musl'
+    : os;
+
   return {
     os,
     arch: archiveArch,
     rid,
-    archive: `blok-server_${os}_${archiveArch}.${os === 'windows' ? 'zip' : 'tar.gz'}`,
+    archive: `blok-server_${archiveOs}_${archiveArch}.${os === 'windows' ? 'zip' : 'tar.gz'}`,
     binary: os === 'windows' ? 'blok-server.exe' : 'blok-server',
   };
 }
@@ -103,32 +121,44 @@ 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})`,
+    );
+  }
 }
 
 /**
@@ -137,7 +167,9 @@ function firstWritable(candidates) {
  * @returns {Promise<Buffer>}
  */
 async function download(url, fetchImpl) {
-  const response = await fetchImpl(url);
+  const response = await fetchImpl(url, {
+    signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
+  });
 
   if (!response.ok) {
     throw new Error(`GET ${url} → ${response.status} ${response.statusText}`);
@@ -221,6 +253,38 @@ export async function installBinary({ version, target, destination, fetchImpl =
   }
 }
 
+/**
+ * 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
@@ -231,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');
@@ -241,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(
@@ -252,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 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,6 +1,6 @@
 {
   "name": "@bloklabs/server",
-  "version": "1.12.0",
+  "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",
@@ -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;