@syncular/server-hono 0.0.6-96 → 0.2.1

package/dist/index.js

@@ -1,25 +1,136 @@
 /**
- * @syncular/server-hono - Hono adapter for sync infrastructure
- *
- * This package provides Hono-specific routes for @syncular/server.
- * Keeps @syncular/server framework-agnostic.
+ * Hono adapter (REVISE B2): a thin wrapper proving the embed boundary.
+ * Hono is a dependency of this adapter only, never of the server core.
+ * Mounts the §1.1 routes: POST /sync and GET /segments/:segmentId
+ * (realtime upgrades are runtime-specific and stay with the host).
  */
-// API Key Auth
-export * from './api-key-auth.js';
-// Blob routes
-export { createBlobRoutes } from './blobs.js';
-// Console
-export * from './console/index.js';
-// Simplified server factory
-export { createSyncServer, } from './create-server.js';
-// OpenAPI utilities
-export * from './openapi.js';
-// Proxy
-export * from './proxy/index.js';
-// Rate limiting
-export * from './rate-limit.js';
-// Route types and factory
-export { createSyncRoutes, getSyncRealtimeUnsubscribe, getSyncWebSocketConnectionManager, } from './routes.js';
-// WebSocket helpers for realtime sync
-export * from './ws.js';
-//# sourceMappingURL=index.js.map
+import { encodeSegmentBody, errorBody, handleBlobDownload, handleBlobUpload, handleBlobUploadGrant, handleSegmentDownload, handleSyncRequest, SSP2_CONTENT_TYPE, SyncError, } from '@syncular/server';
+import { Hono } from 'hono';
+export * from './admin.js';
+function errorResponse(error) {
+    const sync = error instanceof SyncError
+        ? error
+        : new SyncError('sync.invalid_request', String(error));
+    return Response.json(errorBody(sync), { status: sync.httpStatus });
+}
+export function createSyncularHono(options) {
+    const app = new Hono();
+    app.post('/sync', async (c) => {
+        const contentType = c.req.header('content-type')?.split(';')[0]?.trim();
+        if (contentType !== SSP2_CONTENT_TYPE) {
+            // §1.1: any other content type is rejected with HTTP 415.
+            return Response.json(errorBody(new SyncError('sync.invalid_request', 'unsupported content type')), { status: 415 });
+        }
+        const auth = await options.authenticate(c.req.raw);
+        if (auth === null)
+            return errorResponse(new SyncError('sync.auth_required'));
+        try {
+            const bytes = new Uint8Array(await c.req.arrayBuffer());
+            const out = await handleSyncRequest(bytes, {
+                ...options.config,
+                ...auth,
+            });
+            return c.body(out.slice().buffer, 200, {
+                'Content-Type': SSP2_CONTENT_TYPE,
+            });
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    });
+    app.get('/segments/:segmentId', async (c) => {
+        const auth = await options.authenticate(c.req.raw);
+        if (auth === null)
+            return errorResponse(new SyncError('sync.auth_required'));
+        try {
+            const result = await handleSegmentDownload({ ...options.config, ...auth }, {
+                segmentId: c.req.param('segmentId'),
+                scopesHeader: c.req.header('x-syncular-scopes') ?? '{}',
+            });
+            if (c.req.header('if-none-match') === result.headers.ETag) {
+                return c.body(null, 304, result.headers);
+            }
+            // §5.8 shipped default: compress the body per Accept-Encoding
+            // (zstd preferred, gzip fallback, identity otherwise). Content
+            // addresses are over the uncompressed bytes (§5.1) — fetch
+            // decodes transparently on the client.
+            const encoded = encodeSegmentBody(result.bytes, c.req.header('accept-encoding'));
+            return c.body(encoded.bytes.slice().buffer, 200, {
+                ...result.headers,
+                ...(encoded.contentEncoding !== undefined
+                    ? { 'Content-Encoding': encoded.contentEncoding }
+                    : {}),
+            });
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    });
+    // §5.9.3: blob upload with server-side content-address verification.
+    app.put('/blobs/:blobId', async (c) => {
+        const auth = await options.authenticate(c.req.raw);
+        if (auth === null)
+            return errorResponse(new SyncError('sync.auth_required'));
+        try {
+            const bytes = new Uint8Array(await c.req.arrayBuffer());
+            const contentType = c.req.header('content-type')?.split(';')[0]?.trim();
+            await handleBlobUpload({ ...options.config, ...auth }, {
+                blobId: c.req.param('blobId'),
+                bytes,
+                ...(contentType !== undefined &&
+                    contentType !== 'application/octet-stream'
+                    ? { mediaType: contentType }
+                    : {}),
+            });
+            return c.body(null, 200);
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    });
+    // §5.9.3: presigned-upload grant — mint a direct-to-storage PUT URL.
+    app.post('/blobs/:blobId/upload-grant', async (c) => {
+        const auth = await options.authenticate(c.req.raw);
+        if (auth === null)
+            return errorResponse(new SyncError('sync.auth_required'));
+        try {
+            const body = (await c.req.json().catch(() => ({})));
+            const grant = await handleBlobUploadGrant({ ...options.config, ...auth }, {
+                blobId: c.req.param('blobId'),
+                byteLength: Number(body.byteLength ?? 0),
+                ...(typeof body.mediaType === 'string'
+                    ? { mediaType: body.mediaType }
+                    : {}),
+            });
+            return c.json(grant, 200);
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    });
+    // §5.9.5: blob download, re-authorized against referencing rows. When the
+    // host configured presigned URLs, the result carries `url` (no bytes) and
+    // the client fetches it directly (§5.9.5 always-issue).
+    app.get('/blobs/:blobId', async (c) => {
+        const auth = await options.authenticate(c.req.raw);
+        if (auth === null)
+            return errorResponse(new SyncError('sync.auth_required'));
+        try {
+            const result = await handleBlobDownload({ ...options.config, ...auth }, c.req.param('blobId'));
+            if (result.url !== undefined) {
+                return c.json({ url: result.url, urlExpiresAtMs: result.urlExpiresAtMs }, 200);
+            }
+            if (c.req.header('if-none-match') === result.headers.ETag) {
+                return c.body(null, 304, result.headers);
+            }
+            const bytes = result.bytes ?? new Uint8Array(0);
+            return c.body(bytes.slice().buffer, 200, {
+                ...result.headers,
+            });
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    });
+    return app;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@syncular/server-hono",
-  "version": "0.0.6-96",
-  "description": "Hono adapter for the Syncular server with OpenAPI support",
+  "version": "0.2.1",
+  "description": "Hono adapter for the Syncular sync server",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
   "homepage": "https://syncular.dev",
@@ -18,71 +18,37 @@
     "offline-first",
     "realtime",
     "database",
-    "typescript",
-    "hono",
-    "openapi"
+    "typescript"
   ],
-  "private": false,
+  "type": "module",
+  "sideEffects": false,
   "publishConfig": {
     "access": "public"
   },
-  "type": "module",
   "exports": {
     ".": {
       "bun": "./src/index.ts",
+      "browser": "./src/index.ts",
       "import": {
         "types": "./dist/index.d.ts",
         "default": "./dist/index.js"
       }
-    },
-    "./blobs": {
-      "bun": "./src/blobs.ts",
-      "import": {
-        "types": "./dist/blobs.d.ts",
-        "default": "./dist/blobs.js"
-      }
-    },
-    "./create-server": {
-      "bun": "./src/create-server.ts",
-      "import": {
-        "types": "./dist/create-server.d.ts",
-        "default": "./dist/create-server.js"
-      }
     }
   },
-  "scripts": {
-    "test": "bun test src/__tests__",
-    "tsgo": "tsgo --noEmit",
-    "generate": "bun generate:openapi",
-    "generate:openapi": "bun scripts/generate-openapi.ts",
-    "build": "tsgo",
-    "release": "bunx syncular-publish"
-  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts"
+  ],
   "dependencies": {
-    "@hono/standard-validator": "^0.2.2",
-    "@standard-community/standard-json": "^0.3.5",
-    "@standard-community/standard-openapi": "^0.2.9",
-    "@syncular/console": "0.0.6-96",
-    "@syncular/core": "0.0.6-96",
-    "@syncular/server": "0.0.6-96",
-    "@types/json-schema": "^7.0.15",
-    "hono-openapi": "^1.2.0",
-    "openapi-types": "^12.1.3"
+    "@syncular/server": "0.2.1",
+    "hono": "^4.11.0"
   },
   "devDependencies": {
-    "@syncular/config": "0.0.0",
-    "@syncular/dialect-pglite": "0.0.6-96",
-    "@syncular/server-dialect-postgres": "0.0.6-96",
-    "kysely": "*",
-    "zod": "*"
-  },
-  "peerDependencies": {
-    "hono": "^4.0.0",
-    "kysely": "^0.28.0",
-    "zod": "^4.0.0"
-  },
-  "files": [
-    "dist",
-    "src"
-  ]
+    "@syncular/core": "0.2.1"
+  }
 }

package/src/admin-page.ts

@@ -0,0 +1,217 @@
+/**
+ * The single static console page (TODO §2.5). Zero framework, no build
+ * step, ~one file: it fetches the sibling JSON endpoints (relative to its
+ * own mount path), renders tables, and offers an auto-refresh toggle. This
+ * is the v2 answer to v1's full React console app — 5% of the code, the
+ * 80% operator value.
+ *
+ * The HTML is a single exported string so the routes module can serve it
+ * with no filesystem read (works identically on Bun, Node, and Workers).
+ * All fetches are same-origin and relative ('./clients', …), so the page
+ * works under whatever prefix the host mounts the routes at, and the host's
+ * `authorize` guard applies to the page's own XHRs (same cookies/headers).
+ */
+export const ADMIN_CONSOLE_HTML = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Syncular console</title>
+<style>
+  :root {
+    --bg: #0f1115; --panel: #171a21; --border: #262b36; --fg: #d7dce5;
+    --muted: #8a93a6; --accent: #5b9dff; --ok: #43c17a; --warn: #e0a83a;
+    --mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
+    --sans: system-ui, -apple-system, Segoe UI, Roboto, sans-serif;
+  }
+  * { box-sizing: border-box; }
+  body { margin: 0; background: var(--bg); color: var(--fg); font: 14px/1.5 var(--sans); }
+  header { display: flex; align-items: center; gap: 16px; flex-wrap: wrap;
+    padding: 14px 20px; border-bottom: 1px solid var(--border); background: var(--panel); }
+  header h1 { font-size: 15px; margin: 0; font-weight: 600; letter-spacing: .02em; }
+  header .spacer { flex: 1; }
+  header label { color: var(--muted); font-size: 13px; display: inline-flex; gap: 6px; align-items: center; }
+  header input[type=text] { background: var(--bg); border: 1px solid var(--border); color: var(--fg);
+    border-radius: 6px; padding: 5px 8px; font: 13px var(--mono); width: 140px; }
+  header button { background: var(--bg); border: 1px solid var(--border); color: var(--fg);
+    border-radius: 6px; padding: 5px 11px; cursor: pointer; font: 13px var(--sans); }
+  header button:hover { border-color: var(--accent); }
+  #status { color: var(--muted); font: 12px var(--mono); }
+  main { padding: 18px 20px; display: grid; gap: 18px; grid-template-columns: repeat(auto-fit, minmax(420px, 1fr)); }
+  section { background: var(--panel); border: 1px solid var(--border); border-radius: 10px; overflow: hidden; }
+  section > h2 { font-size: 13px; margin: 0; padding: 10px 14px; border-bottom: 1px solid var(--border);
+    font-weight: 600; color: var(--fg); display: flex; justify-content: space-between; align-items: center; }
+  section > h2 .count { color: var(--muted); font: 12px var(--mono); font-weight: 400; }
+  .body { max-height: 360px; overflow: auto; }
+  table { width: 100%; border-collapse: collapse; font: 12px var(--mono); }
+  th, td { text-align: left; padding: 6px 10px; border-bottom: 1px solid var(--border); white-space: nowrap; }
+  th { color: var(--muted); font-weight: 500; position: sticky; top: 0; background: var(--panel); z-index: 1; }
+  td.wrap { white-space: normal; word-break: break-all; }
+  tr:hover td { background: #1c212b; }
+  .pill { display: inline-block; padding: 1px 7px; border-radius: 999px; font-size: 11px; }
+  .pill.ok { background: rgba(67,193,122,.15); color: var(--ok); }
+  .pill.warn { background: rgba(224,168,58,.15); color: var(--warn); }
+  .pill.idle { background: rgba(138,147,166,.15); color: var(--muted); }
+  .kv { display: grid; grid-template-columns: auto 1fr; gap: 4px 14px; padding: 10px 14px; font: 12px var(--mono); }
+  .kv dt { color: var(--muted); }
+  .empty { color: var(--muted); padding: 14px; font-style: italic; }
+  .evt-type { color: var(--accent); }
+  .full { grid-column: 1 / -1; }
+</style>
+</head>
+<body>
+<header>
+  <h1>Syncular console</h1>
+  <label>partition
+    <input id="partition" type="text" placeholder="(default)" />
+  </label>
+  <button id="refresh">Refresh</button>
+  <label><input id="auto" type="checkbox" /> auto</label>
+  <span class="spacer"></span>
+  <span id="status">idle</span>
+</header>
+<main>
+  <section><h2>Horizon <span class="count" id="horizon-rec"></span></h2><div class="body" id="horizon"></div></section>
+  <section><h2>Store stats</h2><div class="body" id="stats"></div></section>
+  <section><h2>Clients <span class="count" id="clients-count"></span></h2><div class="body" id="clients"></div></section>
+  <section><h2>Recent commits <span class="count" id="commits-count"></span></h2><div class="body" id="commits"></div></section>
+  <section class="full"><h2>Event stream <span class="count" id="events-count"></span></h2><div class="body" id="events"></div></section>
+</main>
+<script>
+(function () {
+  var el = function (id) { return document.getElementById(id); };
+  var status = el('status');
+
+  function q() {
+    var p = el('partition').value.trim();
+    return p ? ('?partition=' + encodeURIComponent(p)) : '';
+  }
+  // The endpoints are siblings of the page under the SAME mount prefix. The
+  // page is served at the mount root (…/admin or …/admin/); strip any
+  // trailing slash so 'base + /clients' hits '…/admin/clients' regardless of
+  // whether the URL had the trailing slash.
+  var base = location.pathname.replace(/\\/+$/, '');
+  function get(path) {
+    return fetch(base + path + q(), { headers: { accept: 'application/json' } })
+      .then(function (r) {
+        if (!r.ok) return r.json().then(function (b) { throw new Error(b.code || ('HTTP ' + r.status)); });
+        return r.json();
+      });
+  }
+  function esc(v) {
+    return String(v == null ? '' : v)
+      .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+  }
+  function ago(ms) {
+    var d = Date.now() - ms;
+    if (d < 0) d = 0;
+    if (d < 1000) return d + 'ms';
+    if (d < 60000) return Math.round(d / 1000) + 's';
+    if (d < 3600000) return Math.round(d / 60000) + 'm';
+    return Math.round(d / 3600000) + 'h';
+  }
+  function bytes(n) {
+    if (n == null) return '-';
+    if (n < 1024) return n + ' B';
+    if (n < 1048576) return (n / 1024).toFixed(1) + ' KiB';
+    return (n / 1048576).toFixed(1) + ' MiB';
+  }
+  function table(head, rows) {
+    if (!rows.length) return '<div class="empty">none</div>';
+    var h = '<table><thead><tr>' + head.map(function (c) { return '<th>' + esc(c) + '</th>'; }).join('') + '</tr></thead><tbody>';
+    h += rows.map(function (r) {
+      return '<tr>' + r.map(function (c) { return '<td>' + c + '</td>'; }).join('') + '</tr>';
+    }).join('');
+    return h + '</tbody></table>';
+  }
+
+  function renderHorizon(h) {
+    el('horizon').innerHTML =
+      '<dl class="kv">' +
+      '<dt>maxCommitSeq</dt><dd>' + esc(h.maxCommitSeq) + '</dd>' +
+      '<dt>horizonSeq</dt><dd>' + esc(h.horizonSeq) + '</dd>' +
+      '<dt>retained commits</dt><dd>' + esc(h.retainedCommits) + '</dd>' +
+      '<dt>active cursor floor</dt><dd>' + esc(h.activeCursorFloor == null ? 'none' : h.activeCursorFloor) + '</dd>' +
+      '<dt>recommended horizon</dt><dd>' + esc(h.recommendedHorizonSeq) + '</dd>' +
+      '</dl>';
+    var rec = el('horizon-rec');
+    if (h.recommendation === 'prune-recommended') {
+      rec.innerHTML = '<span class="pill warn">prune recommended</span>';
+    } else {
+      rec.innerHTML = '<span class="pill ok">up to date</span>';
+    }
+  }
+  function renderStats(s) {
+    var seg = s.segments, blob = s.blobs;
+    var rows = '<dl class="kv">';
+    if (seg) {
+      rows += '<dt>segments</dt><dd>' + esc(seg.count) + ' (' + bytes(seg.bytes) + ')</dd>' +
+        '<dt>&nbsp;rows / sqlite</dt><dd>' + esc(seg.rowsSegments) + ' / ' + esc(seg.sqliteSegments) + '</dd>';
+    } else { rows += '<dt>segments</dt><dd>n/a</dd>'; }
+    if (blob) {
+      rows += '<dt>blobs</dt><dd>' + esc(blob.count) + ' (' + bytes(blob.bytes) + ')</dd>';
+    } else { rows += '<dt>blobs</dt><dd>n/a</dd>'; }
+    el('stats').innerHTML = rows + '</dl>';
+  }
+  function renderClients(list) {
+    el('clients-count').textContent = list.length + ' known';
+    el('clients').innerHTML = table(['client', 'actor', 'cursor', 'seen', 'subs', ''],
+      list.map(function (c) {
+        var pill = c.active ? '<span class="pill ok">active</span>' : '<span class="pill idle">idle</span>';
+        return [esc(c.clientId), esc(c.actorId), esc(c.cursor), ago(c.updatedAtMs), esc(c.subscriptions.length), pill];
+      }));
+  }
+  function renderCommits(list) {
+    el('commits-count').textContent = list.length + ' shown';
+    el('commits').innerHTML = table(['seq', 'actor', 'client', 'changes', 'tables', 'when'],
+      list.map(function (c) {
+        return [esc(c.commitSeq), esc(c.actorId), esc(c.clientId), esc(c.changeCount),
+          '<span class="wrap">' + esc(c.tables.join(', ')) + '</span>', ago(c.createdAtMs)];
+      }));
+  }
+  function renderEvents(res) {
+    el('events-count').textContent = res.hasEventStream
+      ? (res.events.length + ' events')
+      : 'no ring buffer wired';
+    if (!res.hasEventStream) { el('events').innerHTML = '<div class="empty">no RingBufferEvents wired on this admin</div>'; return; }
+    el('events').innerHTML = table(['when', 'type', 'detail'],
+      res.events.map(function (e) {
+        var detail = Object.keys(e)
+          .filter(function (k) { return k !== 'type' && k !== 'atMs'; })
+          .map(function (k) { return k + '=' + JSON.stringify(e[k]); })
+          .join(' ');
+        return [ago(e.atMs), '<span class="evt-type">' + esc(e.type) + '</span>',
+          '<span class="wrap">' + esc(detail) + '</span>'];
+      }));
+  }
+
+  var loading = false;
+  function loadAll() {
+    if (loading) return;
+    loading = true;
+    status.textContent = 'loading…';
+    Promise.all([
+      get('/horizon').then(function (r) { renderHorizon(r.horizon); }),
+      get('/stats').then(function (r) { renderStats(r.stats); }),
+      get('/clients').then(function (r) { renderClients(r.clients); }),
+      get('/commits').then(function (r) { renderCommits(r.commits); }),
+      get('/events').then(renderEvents)
+    ]).then(function () {
+      status.textContent = 'updated ' + new Date().toLocaleTimeString();
+    }).catch(function (err) {
+      status.textContent = 'error: ' + err.message;
+    }).finally(function () { loading = false; });
+  }
+
+  el('refresh').addEventListener('click', loadAll);
+  el('partition').addEventListener('change', loadAll);
+  var timer = null;
+  el('auto').addEventListener('change', function () {
+    if (this.checked) { timer = setInterval(loadAll, 2000); loadAll(); }
+    else if (timer) { clearInterval(timer); timer = null; }
+  });
+  loadAll();
+})();
+</script>
+</body>
+</html>`;

package/src/admin.ts

@@ -0,0 +1,193 @@
+/**
+ * Admin / console HTTP surface (TODO §2.5) — a mountable Hono sub-app over a
+ * `SyncularAdmin`. JSON endpoints mirror the read surface; a single static
+ * HTML page (zero framework, no build step) at `GET /` renders them.
+ *
+ * The auth seam is REQUIRED. There is NO default-open admin: the factory
+ * refuses to mount without a host-provided `authorize` guard (it throws at
+ * construction). Every request runs the guard first; a falsy result is a
+ * 401. Admin is a privileged surface (it reads every partition's clients,
+ * commit metadata, and scope activity) and SPEC.md deliberately says nothing
+ * about it — authorization is entirely the host's, and mandatory.
+ */
+import {
+  errorBody,
+  type RingEventQuery,
+  SyncError,
+  type SyncularAdmin,
+} from '@syncular/server';
+import { Hono } from 'hono';
+import { ADMIN_CONSOLE_HTML } from './admin-page';
+
+export interface AdminAuthContext {
+  /** The partition the request targets (from the query string / route). */
+  readonly partition: string;
+  readonly request: Request;
+}
+
+export interface SyncularAdminRoutesOptions {
+  /**
+   * REQUIRED host guard. Return `true` (or a truthy value) to allow the
+   * request, a falsy value to reject it with 401. Runs before every admin
+   * endpoint, including the HTML page. There is no default — omitting it
+   * throws, by design (no default-open admin).
+   */
+  readonly authorize: (ctx: AdminAuthContext) => boolean | Promise<boolean>;
+  /**
+   * Default partition for endpoints when the request omits `?partition=`.
+   * When unset, `partition` is required on every data endpoint.
+   */
+  readonly defaultPartition?: string;
+}
+
+function jsonError(error: unknown): Response {
+  const sync =
+    error instanceof SyncError
+      ? error
+      : new SyncError('sync.invalid_request', String(error));
+  return Response.json(errorBody(sync), { status: sync.httpStatus });
+}
+
+function intParam(value: string | undefined, fallback: number): number {
+  if (value === undefined) return fallback;
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+/**
+ * Build the mountable admin sub-app. Mount it under any prefix, e.g.
+ * `app.route('/admin', createSyncularAdminRoutes(admin, { authorize }))`.
+ * Throws if `authorize` is missing — admin never mounts default-open.
+ */
+export function createSyncularAdminRoutes(
+  admin: SyncularAdmin,
+  options: SyncularAdminRoutesOptions,
+): Hono {
+  if (typeof options.authorize !== 'function') {
+    throw new Error(
+      'createSyncularAdminRoutes: an `authorize` guard is required — admin never mounts default-open (TODO §2.5)',
+    );
+  }
+  const app = new Hono();
+
+  /** Resolve the request's partition (query, else default) — required. */
+  function partitionOf(c: {
+    req: { query: (k: string) => string | undefined };
+  }): string {
+    const partition = c.req.query('partition') ?? options.defaultPartition;
+    if (partition === undefined || partition.length === 0) {
+      throw new SyncError('sync.invalid_request', 'partition is required');
+    }
+    return partition;
+  }
+
+  // Guard every route (page + data) up front.
+  app.use('*', async (c, next) => {
+    let partition: string;
+    try {
+      partition = c.req.query('partition') ?? options.defaultPartition ?? '';
+    } catch {
+      partition = '';
+    }
+    const ok = await options.authorize({ partition, request: c.req.raw });
+    if (!ok) return jsonError(new SyncError('sync.auth_required'));
+    await next();
+  });
+
+  // The single static console page (zero framework, no build step).
+  app.get('/', (c) =>
+    c.html(ADMIN_CONSOLE_HTML, 200, { 'Cache-Control': 'no-store' }),
+  );
+
+  app.get('/clients', async (c) => {
+    try {
+      const clients = await admin.listClients(partitionOf(c));
+      return Response.json({ clients });
+    } catch (error) {
+      return jsonError(error);
+    }
+  });
+
+  app.get('/commits', async (c) => {
+    try {
+      const table = c.req.query('table');
+      const commits = await admin.listCommits(partitionOf(c), {
+        afterSeq: intParam(c.req.query('afterSeq'), 0),
+        limit: intParam(c.req.query('limit'), 50),
+        ...(table !== undefined ? { table } : {}),
+      });
+      return Response.json({ commits });
+    } catch (error) {
+      return jsonError(error);
+    }
+  });
+
+  app.get('/rows/:table/:rowId', async (c) => {
+    try {
+      const row = await admin.inspectRow(
+        partitionOf(c),
+        c.req.param('table'),
+        c.req.param('rowId'),
+      );
+      return Response.json({ row });
+    } catch (error) {
+      return jsonError(error);
+    }
+  });
+
+  app.get('/scope-activity', async (c) => {
+    try {
+      const variable = c.req.query('variable');
+      const value = c.req.query('value');
+      if (variable === undefined || value === undefined) {
+        throw new SyncError(
+          'sync.invalid_request',
+          'variable and value are required',
+        );
+      }
+      const activity = await admin.scopeActivity(
+        partitionOf(c),
+        { variable, value },
+        { limit: intParam(c.req.query('limit'), 50) },
+      );
+      return Response.json({ activity });
+    } catch (error) {
+      return jsonError(error);
+    }
+  });
+
+  app.get('/horizon', async (c) => {
+    try {
+      const status = await admin.horizonStatus(partitionOf(c));
+      return Response.json({ horizon: status });
+    } catch (error) {
+      return jsonError(error);
+    }
+  });
+
+  app.get('/stats', async (c) => {
+    try {
+      const stats = await admin.stats(partitionOf(c));
+      return Response.json({ stats });
+    } catch (error) {
+      return jsonError(error);
+    }
+  });
+
+  app.get('/events', async (c) => {
+    try {
+      const type = c.req.query('type') as RingEventQuery['type'];
+      const sinceMs = c.req.query('sinceMs');
+      const events = admin.events({
+        ...(type !== undefined ? { type } : {}),
+        ...(sinceMs !== undefined ? { sinceMs: intParam(sinceMs, 0) } : {}),
+        limit: intParam(c.req.query('limit'), 200),
+      });
+      return Response.json({ events, hasEventStream: admin.hasEventStream });
+    } catch (error) {
+      return jsonError(error);
+    }
+  });
+
+  return app;
+}