@bloklabs/server 1.11.0 → 1.12.0

package/README.md

@@ -1,21 +1,61 @@
 # @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 and link previews. 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.
+The current packages store no documents and include no database-block or MySQL integration. Those features 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;
+  })
+  .UseAuthorization<MyBlokAuthorization>();
+
+var app = builder.Build();
+
+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.
+
+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.
+
+## 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 your platform from the matching GitHub release, verifies it against `checksums.txt`, and caches it.
+
+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:
 
 ```bash
-docker run -p 4000:4000 ghcr.io/jackuait/blok-server --listen 0.0.0.0:4000
+docker run --network host ghcr.io/jackuait/blok-server \
+  --listen 127.0.0.1:4000 \
+  --auth proxy
 ```
 
+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.
+
 ## Point the editor at it
 
 ```ts
@@ -29,37 +69,30 @@ new Blok({
 
       body.append('file', file);
 
-      const res = await fetch('http://127.0.0.1:4000/upload', { method: 'POST', body });
+      const response = await fetch('/api/blok/upload', {
+        method: 'POST',
+        body,
+      });
 
-      return res.json();
+      return response.json();
     },
   },
 });
 ```
 
-The response shapes match what Blok's own parsers already expect, so nothing on the editor side needs configuring beyond the URL.
+The standalone host uses routes at the root. An ASP.NET Core app uses the prefix passed to `MapBlokServer`.
 
 ## 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 |
-
-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.
-
-## Access modes
-
-`--auth` picks who may call the service, and the process refuses to start on a combination that would leave it open:
-
-- `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.
+| `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 |
 
-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.
+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.
 
 ## 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,15 +1,12 @@
 #!/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 execs 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 { createHash } from 'node:crypto';
@@ -24,28 +21,33 @@ const CHECKSUMS_FILE = 'checksums.txt';
 
 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 {string} platform - process.platform
  * @param {string} arch - process.arch
- * @returns {{ os: string, arch: string, archive: string, binary: string } | null}
+ * @returns {{ os: string, arch: string, rid: string, archive: string, binary: string } | null}
  */
 export function resolveTarget(platform, arch) {
   const os = PLATFORMS[platform];
-  const goarch = ARCHITECTURES[arch];
+  const archiveArch = ARCHITECTURES[arch];
+  const rid = 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.
   return {
     os,
-    arch: goarch,
-    archive: `blok-server_${os}_${goarch}.${os === 'windows' ? 'zip' : 'tar.gz'}`,
+    arch: archiveArch,
+    rid,
+    archive: `blok-server_${os}_${archiveArch}.${os === 'windows' ? 'zip' : 'tar.gz'}`,
     binary: os === 'windows' ? 'blok-server.exe' : 'blok-server',
   };
 }
@@ -57,8 +59,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
@@ -131,10 +133,11 @@ function firstWritable(candidates) {
 
 /**
  * @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);
 
   if (!response.ok) {
     throw new Error(`GET ${url} → ${response.status} ${response.statusText}`);
@@ -151,13 +154,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 +176,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) {
@@ -253,7 +262,7 @@ async function main() {
     binary = join(root, target.binary);
 
     if (!existsSync(binary)) {
-      await fetchBinary({ version, target, destination: binary });
+      await installBinary({ version, target, destination: binary });
     }
   } catch (error) {
     console.error(fallbackMessage(version, error.message));

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.12.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",