sh3-server 0.8.2 → 0.9.0

package/dist/packages.js

@@ -18,7 +18,7 @@ function isValidId(id) {
  * For each valid package, mount server routes (if server.js exists) and
  * return the full list of discovered packages.
  */
-export async function loadPackages(shardRouter, dataDir, keys, settings, wsRegister, documentBackend) {
+export async function loadPackages(shardRouter, dataDir, keys, settings, wsRegister, docStore) {
     const packagesDir = join(dataDir, 'packages');
     if (!existsSync(packagesDir)) {
         mkdirSync(packagesDir, { recursive: true });
@@ -68,7 +68,7 @@ export async function loadPackages(shardRouter, dataDir, keys, settings, wsRegis
             };
             if (hasServer) {
                 try {
-                    await shardRouter.mount(manifest.id, serverJs, { pkgDir, keys, settings, wsRegister, documentBackend });
+                    await shardRouter.mount(manifest.id, serverJs, { pkgDir, keys, settings, wsRegister, docStore });
                 }
                 catch (err) {
                     console.warn(`[sh3] ${manifest.id}/server.js failed to load:`, err);
@@ -193,7 +193,7 @@ export function validateRequiredShards(manifest, knownShards) {
  * Returns a Hono router with POST /install and POST /uninstall.
  * Protected by the blanket `/api/*` auth middleware already applied upstream.
  */
-export function createPackageManagementRoutes(shardRouter, dataDir, keys, settings, wsRegister, documentBackend, frameworkShardIds = []) {
+export function createPackageManagementRoutes(shardRouter, dataDir, keys, settings, wsRegister, docStore, frameworkShardIds = []) {
     const router = new Hono();
     router.post('/install', async (c) => {
         const form = await c.req.formData();
@@ -267,7 +267,7 @@ export function createPackageManagementRoutes(shardRouter, dataDir, keys, settin
             writeFileSync(join(pkgDir, 'server.js'), buf);
             // Hot-mount server routes
             try {
-                await shardRouter.mount(id, join(pkgDir, 'server.js'), { pkgDir, keys, settings, wsRegister, documentBackend });
+                await shardRouter.mount(id, join(pkgDir, 'server.js'), { pkgDir, keys, settings, wsRegister, docStore });
             }
             catch (err) {
                 // Roll back entire install — broken server bundle must not be half-installed
@@ -297,7 +297,7 @@ export function createPackageManagementRoutes(shardRouter, dataDir, keys, settin
             return c.json({ error: `Package "${id}" not found` }, 404);
         }
         // Unmount server routes immediately
-        shardRouter.unmount(id);
+        await shardRouter.unmount(id);
         // Remove code files
         rmSync(manifestPath, { force: true });
         const clientPath = join(pkgDir, 'client.js');

package/dist/routes/docs.d.ts

@@ -1,16 +1,20 @@
 /**
  * Document backend API routes.
  *
- * Maps the DocumentBackend interface to HTTP endpoints backed by the
- * local filesystem. Files are stored at {dataDir}/docs/{tenant}/{shard}/{path}.
+ * Delegates every read/write/list/delete to the TenantDocStore, which owns
+ * the metadata-sidecar write pipeline (version bump, syncMode cache, tick
+ * advance, conflict bucket). This router is intentionally thin: it validates
+ * auth and path shape, then calls the store.
  *
- * GET    /api/docs/:tenant/_shards         → listAllShards
- * GET    /api/docs/:tenant/_all            → listAllDocuments
+ * GET    /api/docs/:tenant/_shards         → listAll (shard ids)
+ * GET    /api/docs/:tenant/_all            → listAll
  * GET    /api/docs/:tenant/:shard          → list
  * GET    /api/docs/:tenant/:shard/*path    → read
  * HEAD   /api/docs/:tenant/:shard/*path    → exists
- * PUT    /api/docs/:tenant/:shard/*path    → write (auth required)
- * DELETE /api/docs/:tenant/:shard/*path    → delete (auth required)
+ * PUT    /api/docs/:tenant/:shard/*path    → write
+ * DELETE /api/docs/:tenant/:shard/*path    → delete
  */
 import { Hono } from 'hono';
-export declare function createDocsRouter(dataDir: string): Hono;
+import type { SettingsStore } from '../settings.js';
+import type { TenantDocStore } from '../doc-store/index.js';
+export declare function createDocsRouter(store: TenantDocStore, settings?: SettingsStore): Hono;

package/dist/routes/docs.js

@@ -1,162 +1,128 @@
 /**
  * Document backend API routes.
  *
- * Maps the DocumentBackend interface to HTTP endpoints backed by the
- * local filesystem. Files are stored at {dataDir}/docs/{tenant}/{shard}/{path}.
+ * Delegates every read/write/list/delete to the TenantDocStore, which owns
+ * the metadata-sidecar write pipeline (version bump, syncMode cache, tick
+ * advance, conflict bucket). This router is intentionally thin: it validates
+ * auth and path shape, then calls the store.
  *
- * GET    /api/docs/:tenant/_shards         → listAllShards
- * GET    /api/docs/:tenant/_all            → listAllDocuments
+ * GET    /api/docs/:tenant/_shards         → listAll (shard ids)
+ * GET    /api/docs/:tenant/_all            → listAll
  * GET    /api/docs/:tenant/:shard          → list
  * GET    /api/docs/:tenant/:shard/*path    → read
  * HEAD   /api/docs/:tenant/:shard/*path    → exists
- * PUT    /api/docs/:tenant/:shard/*path    → write (auth required)
- * DELETE /api/docs/:tenant/:shard/*path    → delete (auth required)
+ * PUT    /api/docs/:tenant/:shard/*path    → write
+ * DELETE /api/docs/:tenant/:shard/*path    → delete
  */
 import { Hono } from 'hono';
-import { readFileSync, writeFileSync, unlinkSync, existsSync, mkdirSync, statSync, readdirSync, } from 'node:fs';
-import { join, dirname, relative } from 'node:path';
-export function createDocsRouter(dataDir) {
+import { tenantParamMatch } from '../scope.js';
+export function createDocsRouter(store, settings) {
     const router = new Hono();
-    const docsDir = join(dataDir, 'docs');
-    function resolvePath(tenant, shard, filePath) {
-        // Prevent path traversal
-        const resolved = join(docsDir, tenant, shard, filePath);
-        if (!resolved.startsWith(join(docsDir, tenant, shard))) {
-            throw new Error('Path traversal detected');
-        }
-        return resolved;
+    router.use('/:tenant/*', tenantParamMatch('tenant', settings));
+    router.use('/:tenant', tenantParamMatch('tenant', settings));
+    function isReservedShardId(shard) {
+        return shard.startsWith('__');
     }
-    function collectFiles(dir, base) {
-        const results = [];
-        if (!existsSync(dir))
-            return results;
-        const entries = readdirSync(dir, { withFileTypes: true });
-        for (const entry of entries) {
-            const full = join(dir, entry.name);
-            if (entry.isDirectory()) {
-                results.push(...collectFiles(full, base));
-            }
-            else {
-                const stat = statSync(full);
-                results.push({
-                    path: relative(base, full).replace(/\\/g, '/'),
-                    size: stat.size,
-                    lastModified: stat.mtimeMs,
-                });
-            }
-        }
-        return results;
-    }
-    // List all shard ids that have content for a tenant.
-    router.get('/:tenant/_shards', (c) => {
+    // Shards list
+    router.get('/:tenant/_shards', async (c) => {
         const { tenant } = c.req.param();
-        const tenantDir = join(docsDir, tenant);
-        if (!existsSync(tenantDir))
-            return c.json([]);
-        const entries = readdirSync(tenantDir, { withFileTypes: true });
-        const shards = entries.filter((e) => e.isDirectory()).map((e) => e.name);
-        return c.json(shards);
+        const all = await store.listAll(tenant);
+        const seen = new Set();
+        for (const e of all)
+            seen.add(e.shardId);
+        return c.json([...seen].filter((id) => !isReservedShardId(id)));
     });
-    // Tenant-wide document list with shardId attached on each entry.
-    router.get('/:tenant/_all', (c) => {
+    // All docs
+    router.get('/:tenant/_all', async (c) => {
         const { tenant } = c.req.param();
-        const tenantDir = join(docsDir, tenant);
-        if (!existsSync(tenantDir))
-            return c.json([]);
-        const entries = readdirSync(tenantDir, { withFileTypes: true });
-        const out = [];
-        for (const entry of entries) {
-            if (!entry.isDirectory())
-                continue;
-            const shardDir = join(tenantDir, entry.name);
-            for (const f of collectFiles(shardDir, shardDir)) {
-                out.push({ ...f, shardId: entry.name });
-            }
-        }
-        return c.json(out);
+        return c.json(await store.listAll(tenant));
     });
-    // List documents for a tenant/shard
-    router.get('/:tenant/:shard', (c) => {
+    // Per-shard list
+    router.get('/:tenant/:shard', async (c) => {
         const { tenant, shard } = c.req.param();
-        const dir = join(docsDir, tenant, shard);
-        const files = collectFiles(dir, dir);
-        return c.json(files);
+        if (isReservedShardId(shard))
+            return c.notFound();
+        return c.json(await store.list(tenant, shard));
     });
-    // Read a document
-    router.get('/:tenant/:shard/*', (c) => {
+    // Read
+    router.get('/:tenant/:shard/*', async (c) => {
         const { tenant, shard } = c.req.param();
+        if (isReservedShardId(shard))
+            return c.notFound();
         const filePath = c.req.path.replace(`/api/docs/${tenant}/${shard}/`, '');
         if (!filePath)
             return c.json({ error: 'Missing file path' }, 400);
-        let resolved;
-        try {
-            resolved = resolvePath(tenant, shard, filePath);
-        }
-        catch {
-            return c.json({ error: 'Invalid path' }, 400);
+        if (c.req.query('meta') === '1') {
+            const meta = await store.readMeta(tenant, shard, filePath);
+            if (!meta)
+                return c.json({ exists: false });
+            const payload = { exists: true, ...meta };
+            if (meta.syncState === 'conflict') {
+                const cf = await store.readConflict(tenant, shard, filePath);
+                if (cf) {
+                    payload.branches = cf.branches.map((b) => ({
+                        origin: b.origin,
+                        version: b.version,
+                        at: b.at,
+                    }));
+                }
+            }
+            return c.json(payload);
         }
-        if (!existsSync(resolved)) {
+        const content = await store.read(tenant, shard, filePath);
+        if (content === null)
             return c.notFound();
-        }
-        const content = readFileSync(resolved);
-        // Detect binary vs text heuristically: if the file can be decoded as
-        // UTF-8 without replacement characters, treat as text.
-        const text = new TextDecoder('utf-8', { fatal: true });
-        try {
-            const str = text.decode(content);
-            return c.text(str);
-        }
-        catch {
-            return new Response(content, {
-                headers: { 'Content-Type': 'application/octet-stream' },
-            });
-        }
+        return c.text(content);
     });
-    // Check existence via HEAD request
-    router.on('HEAD', '/:tenant/:shard/*', (c) => {
+    // Exists
+    router.on('HEAD', '/:tenant/:shard/*', async (c) => {
         const { tenant, shard } = c.req.param();
+        if (isReservedShardId(shard))
+            return c.notFound();
         const filePath = c.req.path.replace(`/api/docs/${tenant}/${shard}/`, '');
-        let resolved;
-        try {
-            resolved = resolvePath(tenant, shard, filePath);
+        return new Response(null, {
+            status: (await store.exists(tenant, shard, filePath)) ? 200 : 404,
+        });
+    });
+    // Conflict resolve — must match before the generic PUT so the `/resolve`
+    // suffix isn't captured as part of the file path.
+    router.post('/:tenant/:shard/*', async (c) => {
+        const { tenant, shard } = c.req.param();
+        if (isReservedShardId(shard))
+            return c.json({ error: 'Reserved shard id' }, 400);
+        const rawPath = c.req.path.replace(`/api/docs/${tenant}/${shard}/`, '');
+        if (!rawPath.endsWith('/resolve')) {
+            return c.json({ error: 'Unknown docs POST endpoint' }, 404);
         }
-        catch {
-            return new Response(null, { status: 400 });
+        const filePath = rawPath.replace(/\/resolve$/, '');
+        if (!filePath)
+            return c.json({ error: 'Missing file path' }, 400);
+        const body = await c.req.json().catch(() => null);
+        if (!body || typeof body.choice === 'undefined') {
+            return c.json({ error: 'Body must include { choice }' }, 400);
         }
-        return new Response(null, { status: existsSync(resolved) ? 200 : 404 });
+        await store.resolveConflict(tenant, shard, filePath, body.choice);
+        return c.json({ ok: true });
     });
-    // Write a document (auth required via middleware)
+    // Write
     router.put('/:tenant/:shard/*', async (c) => {
         const { tenant, shard } = c.req.param();
+        if (isReservedShardId(shard))
+            return c.json({ error: 'Reserved shard id' }, 400);
         const filePath = c.req.path.replace(`/api/docs/${tenant}/${shard}/`, '');
         if (!filePath)
             return c.json({ error: 'Missing file path' }, 400);
-        let resolved;
-        try {
-            resolved = resolvePath(tenant, shard, filePath);
-        }
-        catch {
-            return c.json({ error: 'Invalid path' }, 400);
-        }
-        mkdirSync(dirname(resolved), { recursive: true });
-        const body = await c.req.arrayBuffer();
-        writeFileSync(resolved, Buffer.from(body));
-        return c.json({ ok: true });
+        const body = await c.req.text();
+        const result = await store.write(tenant, shard, filePath, body);
+        return c.json({ ok: true, ...result });
     });
-    // Delete a document (auth required via middleware)
-    router.delete('/:tenant/:shard/*', (c) => {
+    // Delete
+    router.delete('/:tenant/:shard/*', async (c) => {
         const { tenant, shard } = c.req.param();
+        if (isReservedShardId(shard))
+            return c.json({ error: 'Reserved shard id' }, 400);
         const filePath = c.req.path.replace(`/api/docs/${tenant}/${shard}/`, '');
-        let resolved;
-        try {
-            resolved = resolvePath(tenant, shard, filePath);
-        }
-        catch {
-            return c.json({ error: 'Invalid path' }, 400);
-        }
-        if (existsSync(resolved)) {
-            unlinkSync(resolved);
-        }
+        await store.delete(tenant, shard, filePath);
         return c.json({ ok: true });
     });
     return router;

package/dist/routes/keys.js

@@ -62,7 +62,8 @@ export function createKeysRouter(keys, onRevoke) {
             shardId: body.shardId,
             label: body.label,
             scopes: body.scopes,
-            connectorId: body.connectorId,
+            peerRole: body.peerRole,
+            peerId: body.peerId,
             expiresIn: body.expiresIn,
             tenantId: caller.tenantId,
             userId: caller.userId,
@@ -102,7 +103,8 @@ export function createKeysRouter(keys, onRevoke) {
             ownerUserId: entry.userId,
             mintedByShardId: entry.shardId,
             scopes: entry.scopes,
-            connectorId: entry.connectorId,
+            peerRole: entry.peerRole,
+            peerId: entry.peerId,
             expiresAt,
         });
         return c.json({ id: row.id, key: row.key });

package/dist/scope.d.ts

@@ -5,5 +5,7 @@
  * tenantRequired — 401 unless caller.tenantId is non-null.
  */
 import type { MiddlewareHandler } from 'hono';
+import type { SettingsStore } from './settings.js';
 export declare function scopeRequired(scope: string): MiddlewareHandler;
 export declare const tenantRequired: MiddlewareHandler;
+export declare function tenantParamMatch(paramName: string, settings?: SettingsStore): MiddlewareHandler;

package/dist/scope.js

@@ -23,3 +23,23 @@ export const tenantRequired = async (c, next) => {
         return c.json({ error: 'Tenant-scoped credentials required' }, 401);
     return next();
 };
+export function tenantParamMatch(paramName, settings) {
+    return async (c, next) => {
+        // Open / no-auth mode: admin has explicitly disabled tenant isolation.
+        // Mirrors sessionAuth's open-mode bypass; required for Tauri sidecar mode.
+        if (settings && !settings.get().auth.required)
+            return next();
+        const caller = c.get('caller');
+        if (!caller)
+            return c.json({ error: 'Caller not resolved' }, 500);
+        if (caller.scopes.includes('admin:*'))
+            return next();
+        if (!caller.tenantId)
+            return c.json({ error: 'Tenant-scoped credentials required' }, 401);
+        const requested = c.req.param(paramName);
+        if (caller.tenantId !== requested) {
+            return c.json({ error: `Caller tenant does not match :${paramName}` }, 403);
+        }
+        return next();
+    };
+}

package/dist/shard-router.d.ts

@@ -2,12 +2,12 @@ import { Hono } from 'hono';
 import type { MiddlewareHandler } from 'hono';
 import type { KeyStore } from './keys.js';
 import type { SettingsStore } from './settings.js';
+import type { TenantDocStore } from './doc-store/index.js';
 export interface MountContext {
     pkgDir: string;
     keys: KeyStore;
     settings: SettingsStore;
-    /** The server's document backend, for sync handle construction. */
-    documentBackend: import('sh3-core/server-sync').DocumentBackend;
+    docStore: TenantDocStore;
     /**
      * Register a WebSocket upgrade handler on a path under this shard's
      * route prefix. The returned value is a Hono middleware handler that
@@ -49,16 +49,12 @@ export interface MountContext {
 }
 /** Middleware requiring the caller's scope set to include admin:*. */
 export declare function adminOnly(_keys: KeyStore, settings: SettingsStore): MiddlewareHandler;
-/**
- * Build a ServerShardContext object for the given shard, wiring
- * sync/syncRegistry based on the declared permissions.
- */
-export declare function buildShardCtx(shardId: string, dataDir: string, permissions: string[], keys: KeyStore, settings: SettingsStore, wsRegister: MountContext['wsRegister'], documentBackend: MountContext['documentBackend']): Record<string, unknown>;
 /**
  * Dynamic shard route manager. Holds a Map of shard Hono sub-apps
  * and delegates requests from a single wildcard route.
  */
 export declare class ShardRouter {
+    #private;
     private shards;
     /**
      * Import a server.js bundle and mount its routes.
@@ -73,9 +69,12 @@ export declare class ShardRouter {
     mountStatic(shardId: string, mod: {
         id: string;
         routes: (router: Hono, ctx: any) => void | Promise<void>;
+        teardown?: () => void | Promise<void>;
     }, ctx: MountContext): Promise<void>;
-    /** Remove a shard's routes. */
-    unmount(shardId: string): boolean;
+    /** Remove a shard's routes. Calls `teardown()` if the shard defined one. */
+    unmount(shardId: string): Promise<boolean>;
+    /** Call teardown on every mounted shard without clearing the registry. */
+    unmountAll(): Promise<void>;
     /**
      * Hono handler for the wildcard route.
      * Looks up the shard sub-app and delegates with path stripping.