sh3-server 0.8.1 → 0.9.0

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.d.ts

@@ -0,0 +1,21 @@
+/**
+ * User-tenant key management endpoints.
+ *
+ * Auth: uses `caller.tenantId` set by resolveCaller. Each caller can only
+ * see and revoke keys in their own tenant.
+ *
+ * Mint flow:
+ *   1. Shell calls POST /consent (session-only) → receives a short-lived ticket.
+ *   2. Shard calls POST / with the ticket → key is generated and returned once.
+ *
+ * Tickets are single-use and expire after TICKET_TTL_MS (60 s).
+ */
+import { Hono } from 'hono';
+import type { KeyStore, ApiKeyPublic } from '../keys.js';
+export interface RevocationEvent {
+    tenantId: string;
+    id: string;
+    row: ApiKeyPublic;
+}
+export type RevocationHook = (event: RevocationEvent) => Promise<void> | void;
+export declare function createKeysRouter(keys: KeyStore, onRevoke: RevocationHook): Hono;

package/dist/routes/keys.js

@@ -0,0 +1,166 @@
+/**
+ * User-tenant key management endpoints.
+ *
+ * Auth: uses `caller.tenantId` set by resolveCaller. Each caller can only
+ * see and revoke keys in their own tenant.
+ *
+ * Mint flow:
+ *   1. Shell calls POST /consent (session-only) → receives a short-lived ticket.
+ *   2. Shard calls POST / with the ticket → key is generated and returned once.
+ *
+ * Tickets are single-use and expire after TICKET_TTL_MS (60 s).
+ */
+import { Hono } from 'hono';
+import { randomBytes } from 'node:crypto';
+import { tenantRequired } from '../scope.js';
+const TICKET_TTL_MS = 60_000;
+function sweepExpired(tickets) {
+    const now = Date.now();
+    for (const [token, entry] of tickets) {
+        if (now - entry.issuedAt > TICKET_TTL_MS)
+            tickets.delete(token);
+    }
+}
+export function createKeysRouter(keys, onRevoke) {
+    const router = new Hono();
+    const tickets = new Map();
+    // SSE subscribers — one entry per connected browser tab.
+    const sseSubscribers = new Set();
+    /** Push a revocation event to all connected SSE listeners. */
+    function pushToBus(ev) {
+        for (const fn of sseSubscribers)
+            fn(ev);
+    }
+    router.use('*', tenantRequired);
+    router.get('/', (c) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const caller = c.get('caller');
+        return c.json(keys.listForTenant(caller.tenantId));
+    });
+    /**
+     * POST /consent — shell-only endpoint that issues a single-use consent ticket.
+     *
+     * Only session-authenticated callers may call this — bearer-token clients
+     * (background shards) must not be able to self-issue consent proofs.
+     */
+    router.post('/consent', async (c) => {
+        sweepExpired(tickets);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const caller = c.get('caller');
+        if (caller.source !== 'session' || !caller.userId) {
+            return c.json({ error: 'Consent requires a logged-in session.' }, 403);
+        }
+        const body = (await c.req.json());
+        if (!body.shardId || !body.label || !Array.isArray(body.scopes)) {
+            return c.json({ error: 'Missing shardId/label/scopes' }, 400);
+        }
+        if (!body.scopes.every((s) => typeof s === 'string')) {
+            return c.json({ error: 'scopes must be an array of strings' }, 400);
+        }
+        const ticket = `tk_${randomBytes(16).toString('hex')}`;
+        tickets.set(ticket, {
+            shardId: body.shardId,
+            label: body.label,
+            scopes: body.scopes,
+            peerRole: body.peerRole,
+            peerId: body.peerId,
+            expiresIn: body.expiresIn,
+            tenantId: caller.tenantId,
+            userId: caller.userId,
+            issuedAt: Date.now(),
+        });
+        return c.json({ ticket });
+    });
+    /**
+     * POST / — mint a key using a valid consent ticket.
+     *
+     * Ticket is consumed on first use (single-use). Expired or unknown tickets
+     * return 400. The full key value is returned exactly once.
+     */
+    router.post('/', async (c) => {
+        sweepExpired(tickets);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const caller = c.get('caller');
+        const body = (await c.req.json());
+        if (!body.ticket)
+            return c.json({ error: 'Missing ticket' }, 400);
+        const entry = tickets.get(body.ticket);
+        tickets.delete(body.ticket); // consume immediately (single-use)
+        if (!entry)
+            return c.json({ error: 'Ticket invalid or already used' }, 400);
+        if (Date.now() - entry.issuedAt > TICKET_TTL_MS) {
+            return c.json({ error: 'Ticket invalid or already used' }, 400);
+        }
+        if (entry.tenantId !== caller.tenantId) {
+            return c.json({ error: 'Ticket invalid or already used' }, 400);
+        }
+        const expiresAt = entry.expiresIn
+            ? new Date(Date.now() + entry.expiresIn).toISOString()
+            : undefined;
+        const row = keys.generate({
+            label: entry.label,
+            tenantId: entry.tenantId,
+            ownerUserId: entry.userId,
+            mintedByShardId: entry.shardId,
+            scopes: entry.scopes,
+            peerRole: entry.peerRole,
+            peerId: entry.peerId,
+            expiresAt,
+        });
+        return c.json({ id: row.id, key: row.key });
+    });
+    /**
+     * GET /events — server-sent events stream.
+     *
+     * Delivers `{ id, shardId }` messages whenever a key belonging to this
+     * tenant is revoked from any source. The client-side revocation bus
+     * consumes this stream and dispatches `onKeyRevoked` on the owning shard.
+     *
+     * Auth: tenantRequired (already applied via the `*` middleware above).
+     * Each connected tab gets its own stream. Connections are cleaned up
+     * automatically when the client disconnects (abort signal).
+     */
+    router.get('/events', (c) => {
+        return new Response(new ReadableStream({
+            start(controller) {
+                const enc = new TextEncoder();
+                const send = (data) => {
+                    controller.enqueue(enc.encode(`data: ${JSON.stringify(data)}\n\n`));
+                };
+                const fn = (ev) => send(ev);
+                sseSubscribers.add(fn);
+                // Send a keepalive comment every 20 s so proxies don't kill idle connections.
+                const heartbeat = setInterval(() => {
+                    try {
+                        controller.enqueue(enc.encode(': ping\n\n'));
+                    }
+                    catch { /* stream closed */ }
+                }, 20_000);
+                c.req.raw.signal?.addEventListener('abort', () => {
+                    clearInterval(heartbeat);
+                    sseSubscribers.delete(fn);
+                    controller.close();
+                });
+            },
+        }), {
+            headers: {
+                'content-type': 'text/event-stream',
+                'cache-control': 'no-cache',
+                connection: 'keep-alive',
+            },
+        });
+    });
+    router.delete('/:id', async (c) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const caller = c.get('caller');
+        const id = c.req.param('id');
+        const removed = keys.revoke(caller.tenantId, id);
+        if (!removed)
+            return c.json({ error: 'Key not found' }, 404);
+        await onRevoke({ tenantId: caller.tenantId, id, row: removed });
+        // Broadcast to SSE subscribers so other browser tabs learn of the revocation.
+        pushToBus({ id, shardId: removed.mintedByShardId ?? null });
+        return c.json({ ok: true });
+    });
+    return router;
+}

package/dist/scope.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Scope-based route guards. Operate on the `caller` set by resolveCaller.
+ *
+ * scopeRequired(scope) — 403 unless caller has that scope or admin:*.
+ * 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

@@ -0,0 +1,45 @@
+/**
+ * Scope-based route guards. Operate on the `caller` set by resolveCaller.
+ *
+ * scopeRequired(scope) — 403 unless caller has that scope or admin:*.
+ * tenantRequired — 401 unless caller.tenantId is non-null.
+ */
+export function scopeRequired(scope) {
+    return async (c, next) => {
+        const caller = c.get('caller');
+        if (!caller)
+            return c.json({ error: 'Caller not resolved' }, 500);
+        if (caller.scopes.includes('admin:*') || caller.scopes.includes(scope)) {
+            return next();
+        }
+        return c.json({ error: `Missing required scope: ${scope}` }, 403);
+    };
+}
+export const tenantRequired = async (c, next) => {
+    const caller = c.get('caller');
+    if (!caller)
+        return c.json({ error: 'Caller not resolved' }, 500);
+    if (!caller.tenantId)
+        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,10 +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;
+    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
@@ -45,13 +47,14 @@ export interface MountContext {
      */
     wsRegister(onConnect: (ws: any, c: any) => void): any;
 }
-/** Middleware that requires admin session OR valid API key. */
-export declare function adminOnly(keys: KeyStore, settings: SettingsStore): MiddlewareHandler;
+/** Middleware requiring the caller's scope set to include admin:*. */
+export declare function adminOnly(_keys: KeyStore, settings: SettingsStore): MiddlewareHandler;
 /**
  * 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.
@@ -66,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.