sh3-server 0.6.0

package/dist/packages.js

@@ -0,0 +1,256 @@
+// Unified package discovery - scans data/packages/ for manifest.json files,
+// mounts server routes, and provides install/uninstall management.
+import { Hono } from 'hono';
+import { readdirSync, readFileSync, existsSync, mkdirSync, writeFileSync, rmSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Validate package ID — alphanumeric, hyphens, underscores, @ for scoped. */
+function isValidId(id) {
+    return /^[a-zA-Z0-9_@-]+$/.test(id);
+}
+// ---------------------------------------------------------------------------
+// Boot-time scanner
+// ---------------------------------------------------------------------------
+/**
+ * Scan `<dataDir>/packages/` for directories containing `manifest.json`.
+ * 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) {
+    const packagesDir = join(dataDir, 'packages');
+    if (!existsSync(packagesDir)) {
+        mkdirSync(packagesDir, { recursive: true });
+        console.log('[sh3] No packages directory — created empty packages/');
+        return [];
+    }
+    const entries = readdirSync(packagesDir, { withFileTypes: true });
+    const dirs = entries.filter((e) => e.isDirectory());
+    if (dirs.length === 0) {
+        console.log('[sh3] No packages found.');
+        return [];
+    }
+    const discovered = [];
+    for (const dir of dirs) {
+        const pkgDir = join(packagesDir, dir.name);
+        const manifestPath = join(pkgDir, 'manifest.json');
+        if (!existsSync(manifestPath)) {
+            continue;
+        }
+        try {
+            const raw = readFileSync(manifestPath, 'utf-8');
+            const manifest = JSON.parse(raw);
+            if (typeof manifest.id !== 'string' || !manifest.id) {
+                console.warn(`[sh3] ${dir.name}/manifest.json missing "id" — skipping`);
+                continue;
+            }
+            if (typeof manifest.type !== 'string' || !manifest.type) {
+                console.warn(`[sh3] ${dir.name}/manifest.json missing "type" — skipping`);
+                continue;
+            }
+            if (typeof manifest.version !== 'string' || !manifest.version) {
+                console.warn(`[sh3] ${dir.name}/manifest.json missing "version" — skipping`);
+                continue;
+            }
+            const clientJs = join(pkgDir, 'client.js');
+            const serverJs = join(pkgDir, 'server.js');
+            const hasClient = existsSync(clientJs);
+            const hasServer = existsSync(serverJs);
+            const pkg = {
+                id: manifest.id,
+                type: manifest.type,
+                label: manifest.label ?? manifest.id,
+                version: manifest.version,
+                contractVersion: manifest.contractVersion ?? 0,
+                ...(hasClient ? { clientPath: resolve(clientJs) } : {}),
+                ...(hasServer ? { serverPath: resolve(serverJs) } : {}),
+            };
+            if (hasServer) {
+                try {
+                    await shardRouter.mount(manifest.id, serverJs, { pkgDir, keys, settings, wsRegister });
+                }
+                catch (err) {
+                    console.warn(`[sh3] ${manifest.id}/server.js failed to load:`, err);
+                }
+            }
+            discovered.push(pkg);
+            console.log(`[sh3]   ${manifest.id} (${manifest.type}) v${manifest.version}` +
+                (hasClient ? ' [client]' : '') +
+                (hasServer ? ' [server]' : ''));
+        }
+        catch (err) {
+            console.warn(`[sh3] Failed to load ${dir.name}/manifest.json — skipping:`, err);
+        }
+    }
+    console.log(`[sh3] Discovered ${discovered.length} package(s).`);
+    return discovered;
+}
+// ---------------------------------------------------------------------------
+// Lightweight re-scan (no route mounting)
+// ---------------------------------------------------------------------------
+/**
+ * Re-scan `<dataDir>/packages/` and return metadata for all valid packages.
+ * Unlike `loadPackages`, this does NOT mount server routes — it only reads
+ * manifests so the listing endpoint always reflects what is on disk.
+ */
+export function scanPackages(dataDir) {
+    const packagesDir = join(dataDir, 'packages');
+    if (!existsSync(packagesDir))
+        return [];
+    const entries = readdirSync(packagesDir, { withFileTypes: true });
+    const result = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const manifestPath = join(packagesDir, entry.name, 'manifest.json');
+        if (!existsSync(manifestPath))
+            continue;
+        try {
+            const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+            if (typeof manifest.id !== 'string' || !manifest.id)
+                continue;
+            if (typeof manifest.type !== 'string' || !manifest.type)
+                continue;
+            if (typeof manifest.version !== 'string' || !manifest.version)
+                continue;
+            const pkgDir = join(packagesDir, entry.name);
+            const hasClient = existsSync(join(pkgDir, 'client.js'));
+            const hasServer = existsSync(join(pkgDir, 'server.js'));
+            result.push({
+                id: manifest.id,
+                type: manifest.type,
+                label: manifest.label ?? manifest.id,
+                version: manifest.version,
+                contractVersion: manifest.contractVersion ?? 0,
+                ...(hasClient ? { clientPath: resolve(join(pkgDir, 'client.js')) } : {}),
+                ...(hasServer ? { serverPath: resolve(join(pkgDir, 'server.js')) } : {}),
+            });
+        }
+        catch {
+            // Skip malformed manifests
+        }
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Client bundle serving
+// ---------------------------------------------------------------------------
+/**
+ * Register `GET /packages/:id/client.js` to serve client bundles from disk.
+ */
+export function servePackageBundles(app, dataDir) {
+    app.get('/packages/:id/client.js', (c) => {
+        const id = c.req.param('id');
+        if (!isValidId(id)) {
+            return c.json({ error: 'Invalid package id' }, 400);
+        }
+        const filePath = join(dataDir, 'packages', id, 'client.js');
+        if (!existsSync(filePath)) {
+            return c.json({ error: 'Client bundle not found' }, 404);
+        }
+        const content = readFileSync(filePath, 'utf-8');
+        return c.body(content, 200, {
+            'Content-Type': 'application/javascript',
+            'Cache-Control': 'public, max-age=31536000, immutable',
+        });
+    });
+}
+// ---------------------------------------------------------------------------
+// Package management routes (install / uninstall)
+// ---------------------------------------------------------------------------
+/**
+ * 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) {
+    const router = new Hono();
+    router.post('/install', async (c) => {
+        const form = await c.req.formData();
+        const manifestFile = form.get('manifest');
+        if (!(manifestFile instanceof File)) {
+            return c.json({ error: 'Missing manifest file' }, 400);
+        }
+        let manifest;
+        try {
+            const text = await manifestFile.text();
+            manifest = JSON.parse(text);
+        }
+        catch {
+            return c.json({ error: 'Invalid manifest JSON' }, 400);
+        }
+        const id = manifest.id;
+        if (typeof id !== 'string' || !id || !isValidId(id)) {
+            return c.json({ error: 'Invalid or missing "id" in manifest' }, 400);
+        }
+        if (typeof manifest.type !== 'string' || !manifest.type) {
+            return c.json({ error: 'Missing "type" in manifest' }, 400);
+        }
+        if (typeof manifest.version !== 'string' || !manifest.version) {
+            return c.json({ error: 'Missing "version" in manifest' }, 400);
+        }
+        const pkgDir = join(dataDir, 'packages', id);
+        mkdirSync(pkgDir, { recursive: true });
+        // Write manifest
+        writeFileSync(join(pkgDir, 'manifest.json'), JSON.stringify(manifest, null, 2));
+        // Write optional client bundle
+        const clientFile = form.get('client');
+        if (clientFile instanceof File) {
+            const buf = Buffer.from(await clientFile.arrayBuffer());
+            writeFileSync(join(pkgDir, 'client.js'), buf);
+        }
+        // Write optional server bundle
+        const serverFile = form.get('server');
+        if (serverFile instanceof File) {
+            const buf = Buffer.from(await serverFile.arrayBuffer());
+            writeFileSync(join(pkgDir, 'server.js'), buf);
+            // Hot-mount server routes
+            try {
+                await shardRouter.mount(id, join(pkgDir, 'server.js'), { pkgDir, keys, settings, wsRegister });
+            }
+            catch (err) {
+                // Roll back entire install — broken server bundle must not be half-installed
+                rmSync(join(pkgDir, 'manifest.json'), { force: true });
+                rmSync(join(pkgDir, 'client.js'), { force: true });
+                rmSync(join(pkgDir, 'server.js'), { force: true });
+                // Remove directory if empty (no pre-existing data/)
+                const dataSubDir = join(pkgDir, 'data');
+                if (!existsSync(dataSubDir) || !statSync(dataSubDir).isDirectory()) {
+                    rmSync(pkgDir, { recursive: true, force: true });
+                }
+                const message = err instanceof Error ? err.message : String(err);
+                return c.json({ error: `Server bundle failed to load: ${message}` }, 422);
+            }
+        }
+        return c.json({ ok: true, id });
+    });
+    router.post('/uninstall', async (c) => {
+        const body = await c.req.json();
+        const id = body.id;
+        if (typeof id !== 'string' || !id || !isValidId(id)) {
+            return c.json({ error: 'Invalid or missing "id"' }, 400);
+        }
+        const pkgDir = join(dataDir, 'packages', id);
+        const manifestPath = join(pkgDir, 'manifest.json');
+        if (!existsSync(manifestPath)) {
+            return c.json({ error: `Package "${id}" not found` }, 404);
+        }
+        // Unmount server routes immediately
+        shardRouter.unmount(id);
+        // Remove code files
+        rmSync(manifestPath, { force: true });
+        const clientPath = join(pkgDir, 'client.js');
+        if (existsSync(clientPath))
+            rmSync(clientPath, { force: true });
+        const serverPath = join(pkgDir, 'server.js');
+        if (existsSync(serverPath))
+            rmSync(serverPath, { force: true });
+        // If no data/ subdirectory, remove the whole package directory
+        const dataSubDir = join(pkgDir, 'data');
+        if (!existsSync(dataSubDir) || !statSync(dataSubDir).isDirectory()) {
+            rmSync(pkgDir, { recursive: true, force: true });
+        }
+        return c.json({ ok: true, id });
+    });
+    return router;
+}

package/dist/routes/admin.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Admin routes — user management, settings, system controls.
+ * All routes require admin session or API key (adminAuth middleware).
+ */
+import { Hono } from 'hono';
+import type { UserStore } from '../users.js';
+import type { SettingsStore } from '../settings.js';
+import type { SessionStore } from '../sessions.js';
+import type { KeyStore } from '../keys.js';
+export declare function createAdminRouter(users: UserStore, settings: SettingsStore, sessions: SessionStore, keys: KeyStore, dataDir: string): Hono;

package/dist/routes/admin.js

@@ -0,0 +1,126 @@
+/**
+ * Admin routes — user management, settings, system controls.
+ * All routes require admin session or API key (adminAuth middleware).
+ */
+import { Hono } from 'hono';
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+export function createAdminRouter(users, settings, sessions, keys, dataDir) {
+    const router = new Hono();
+    // --- Users CRUD ---
+    router.get('/users', (c) => {
+        return c.json(users.list());
+    });
+    router.post('/users', async (c) => {
+        let body;
+        try {
+            body = await c.req.json();
+        }
+        catch {
+            return c.json({ error: 'Invalid JSON body' }, 400);
+        }
+        if (!body.username || !body.password) {
+            return c.json({ error: 'Username and password required' }, 400);
+        }
+        if (body.role && body.role !== 'admin' && body.role !== 'user') {
+            return c.json({ error: 'Role must be "admin" or "user"' }, 400);
+        }
+        try {
+            const user = await users.create({
+                username: body.username,
+                displayName: body.displayName || body.username,
+                password: body.password,
+                role: body.role || 'user',
+            });
+            return c.json(user, 201);
+        }
+        catch (err) {
+            return c.json({ error: err instanceof Error ? err.message : 'Failed to create user' }, 409);
+        }
+    });
+    router.put('/users/:id', async (c) => {
+        const id = c.req.param('id');
+        let body;
+        try {
+            body = await c.req.json();
+        }
+        catch {
+            return c.json({ error: 'Invalid JSON body' }, 400);
+        }
+        if (body.role && body.role !== 'admin' && body.role !== 'user') {
+            return c.json({ error: 'Role must be "admin" or "user"' }, 400);
+        }
+        const updated = await users.update(id, body);
+        if (!updated)
+            return c.json({ error: 'User not found' }, 404);
+        return c.json(updated);
+    });
+    router.delete('/users/:id', (c) => {
+        const id = c.req.param('id');
+        if (!users.delete(id))
+            return c.json({ error: 'User not found' }, 404);
+        return c.body(null, 204);
+    });
+    // --- Settings ---
+    router.get('/settings', (c) => {
+        return c.json(settings.get());
+    });
+    router.put('/settings', async (c) => {
+        let body;
+        try {
+            body = await c.req.json();
+        }
+        catch {
+            return c.json({ error: 'Invalid JSON body' }, 400);
+        }
+        const updated = settings.update(body);
+        // Sync session TTL if changed
+        if (body.auth?.sessionTTL !== undefined) {
+            sessions.setDefaultTTL(body.auth.sessionTTL);
+        }
+        return c.json(updated);
+    });
+    // --- System ---
+    router.post('/restart', (c) => {
+        const scriptPath = join(dataDir, 'restart.sh');
+        if (!existsSync(scriptPath)) {
+            return c.json({
+                error: 'No restart script found',
+                hint: `Create a script at ${scriptPath} to enable remote restart`,
+            }, 404);
+        }
+        // Fire and forget — the server will be killed by the script
+        execFile('bash', [scriptPath], (err) => {
+            if (err)
+                console.error('[sh3] Restart script failed:', err.message);
+        });
+        return c.json({ status: 'restarting' }, 202);
+    });
+    // --- API Keys ---
+    router.get('/keys', (c) => {
+        return c.json(keys.listFull());
+    });
+    router.post('/keys', async (c) => {
+        let body;
+        try {
+            body = await c.req.json();
+        }
+        catch {
+            return c.json({ error: 'Invalid JSON body' }, 400);
+        }
+        const label = body.label?.trim();
+        if (!label) {
+            return c.json({ error: 'Label required' }, 400);
+        }
+        const key = keys.generate(label);
+        return c.json(key, 201);
+    });
+    router.delete('/keys/:id', (c) => {
+        const id = c.req.param('id');
+        if (!keys.revoke(id))
+            return c.json({ error: 'Key not found' }, 404);
+        return c.body(null, 204);
+    });
+    return router;
+}

package/dist/routes/auth.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Auth routes.
+ *
+ * POST /api/auth/login   — authenticate with username + password, set session cookie
+ * POST /api/auth/logout  — clear session, delete cookie
+ * POST /api/auth/verify  — validate an API key (for external tools)
+ */
+import { Hono } from 'hono';
+import type { KeyStore } from '../keys.js';
+import type { UserStore } from '../users.js';
+import type { SessionStore } from '../sessions.js';
+import type { SettingsStore } from '../settings.js';
+export declare function createAuthRouter(keys: KeyStore, users: UserStore, sessions: SessionStore, settings: SettingsStore): Hono;

package/dist/routes/auth.js

@@ -0,0 +1,97 @@
+/**
+ * Auth routes.
+ *
+ * POST /api/auth/login   — authenticate with username + password, set session cookie
+ * POST /api/auth/logout  — clear session, delete cookie
+ * POST /api/auth/verify  — validate an API key (for external tools)
+ */
+import { Hono } from 'hono';
+import { setSessionCookie, clearSessionCookie } from '../auth.js';
+export function createAuthRouter(keys, users, sessions, settings) {
+    const router = new Hono();
+    router.post('/login', async (c) => {
+        let body;
+        try {
+            body = await c.req.json();
+        }
+        catch {
+            return c.json({ error: 'Invalid JSON body' }, 400);
+        }
+        if (!body.username || !body.password) {
+            return c.json({ error: 'Username and password required' }, 400);
+        }
+        const user = await users.authenticate(body.username, body.password);
+        if (!user) {
+            return c.json({ error: 'Invalid credentials' }, 401);
+        }
+        const config = settings.get();
+        const session = sessions.create(user.id, user.role, config.auth.sessionTTL);
+        const maxAge = config.auth.sessionTTL * 3600;
+        setSessionCookie(c, session.token, maxAge);
+        return c.json({
+            session: {
+                token: session.token,
+                userId: session.userId,
+                role: session.role,
+                expiresAt: session.expiresAt,
+            },
+            user,
+        });
+    });
+    router.post('/logout', async (c) => {
+        // Extract session token from cookie
+        const cookie = c.req.raw.headers.get('cookie');
+        if (cookie) {
+            const match = cookie.match(/(?:^|;\s*)sh3_session=([^\s;]+)/);
+            if (match) {
+                sessions.revoke(match[1]);
+            }
+        }
+        clearSessionCookie(c);
+        return c.body(null, 204);
+    });
+    router.post('/register', async (c) => {
+        const config = settings.get();
+        if (!config.auth.selfRegistration) {
+            return c.json({ error: 'Registration is disabled' }, 403);
+        }
+        let body;
+        try {
+            body = await c.req.json();
+        }
+        catch {
+            return c.json({ error: 'Invalid JSON body' }, 400);
+        }
+        if (!body.username || !body.password) {
+            return c.json({ error: 'Username and password required' }, 400);
+        }
+        try {
+            const user = await users.create({
+                username: body.username,
+                displayName: body.displayName || body.username,
+                password: body.password,
+                role: 'user',
+            });
+            const session = sessions.create(user.id, user.role, config.auth.sessionTTL);
+            const maxAge = config.auth.sessionTTL * 3600;
+            setSessionCookie(c, session.token, maxAge);
+            return c.json({ session: { token: session.token, userId: session.userId, role: session.role, expiresAt: session.expiresAt }, user }, 201);
+        }
+        catch (err) {
+            return c.json({ error: err instanceof Error ? err.message : 'Registration failed' }, 409);
+        }
+    });
+    // API key verification — for external tools / CLI
+    router.post('/verify', async (c) => {
+        const authHeader = c.req.header('Authorization');
+        if (!authHeader || !authHeader.startsWith('Bearer ')) {
+            return c.json({ valid: false }, 401);
+        }
+        const token = authHeader.slice(7);
+        if (keys.validate(token)) {
+            return c.json({ valid: true });
+        }
+        return c.json({ valid: false }, 401);
+    });
+    return router;
+}

package/dist/routes/boot.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Boot config endpoint — GET /api/boot
+ *
+ * Returns everything the client needs to decide how to render:
+ * auth requirements, current session, user, and tenant ID.
+ */
+import { Hono } from 'hono';
+import type { SessionStore } from '../sessions.js';
+import type { UserStore } from '../users.js';
+import type { SettingsStore } from '../settings.js';
+export declare function createBootRouter(sessions: SessionStore, users: UserStore, settings: SettingsStore): Hono;

package/dist/routes/boot.js

@@ -0,0 +1,56 @@
+/**
+ * Boot config endpoint — GET /api/boot
+ *
+ * Returns everything the client needs to decide how to render:
+ * auth requirements, current session, user, and tenant ID.
+ */
+import { Hono } from 'hono';
+import { randomUUID } from 'node:crypto';
+export function createBootRouter(sessions, users, settings) {
+    const router = new Hono();
+    router.get('/', (c) => {
+        const config = settings.get();
+        // Try to extract session
+        let session = null;
+        const cookie = c.req.raw.headers.get('cookie');
+        if (cookie) {
+            const match = cookie.match(/(?:^|;\s*)sh3_session=([^\s;]+)/);
+            if (match)
+                session = sessions.validate(match[1]);
+        }
+        if (!session) {
+            const auth = c.req.header('Authorization');
+            if (auth?.startsWith('Bearer sh3s_')) {
+                session = sessions.validate(auth.slice(7));
+            }
+        }
+        const user = session ? users.get(session.userId) : null;
+        // Determine tenant ID
+        let tenantId;
+        if (user) {
+            tenantId = user.id;
+        }
+        else if (!config.auth.required || config.auth.guestAllowed) {
+            tenantId = `guest_${randomUUID()}`;
+        }
+        else {
+            tenantId = 'none';
+        }
+        return c.json({
+            auth: {
+                required: config.auth.required,
+                guestAllowed: config.auth.guestAllowed,
+                selfRegistration: config.auth.selfRegistration,
+            },
+            user,
+            session: session ? {
+                token: session.token,
+                userId: session.userId,
+                role: session.role,
+                expiresAt: session.expiresAt,
+            } : null,
+            tenantId,
+        });
+    });
+    return router;
+}

package/dist/routes/docs.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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}.
+ *
+ * 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)
+ */
+import { Hono } from 'hono';
+export declare function createDocsRouter(dataDir: string): Hono;