sh3-server 0.6.0

package/dist/auth.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Auth middleware — three-tier model.
+ *
+ * 1. Public routes — no auth check (handled by route ordering, not this middleware)
+ * 2. Session required — validates session token from cookie or Authorization header
+ * 3. Admin required — session with admin role OR valid API key
+ *
+ * Session tokens use the `sh3_session` cookie (httpOnly, SameSite=Lax)
+ * or the Authorization header with `Bearer sh3s_*` prefix.
+ * API keys use the Authorization header with `Bearer sh3_*` prefix.
+ */
+import type { MiddlewareHandler, Context } from 'hono';
+import type { KeyStore } from './keys.js';
+import type { SessionStore } from './sessions.js';
+import type { SettingsStore } from './settings.js';
+/**
+ * Session middleware — requires a valid session on non-GET requests
+ * when auth is required. Attaches session to context variable.
+ * GET requests pass through with session attached if present.
+ */
+export declare function sessionAuth(sessions: SessionStore, settings: SettingsStore): MiddlewareHandler;
+/**
+ * Admin middleware — requires admin session OR valid API key.
+ * Must be mounted after sessionAuth so c.get('session') is available.
+ */
+export declare function adminAuth(sessions: SessionStore, keys: KeyStore, settings?: SettingsStore): MiddlewareHandler;
+/**
+ * Helper to set the session cookie on login.
+ */
+export declare function setSessionCookie(c: Context, token: string, maxAgeSeconds: number): void;
+/**
+ * Helper to clear the session cookie on logout.
+ */
+export declare function clearSessionCookie(c: Context): void;

package/dist/auth.js

@@ -0,0 +1,107 @@
+/**
+ * Auth middleware — three-tier model.
+ *
+ * 1. Public routes — no auth check (handled by route ordering, not this middleware)
+ * 2. Session required — validates session token from cookie or Authorization header
+ * 3. Admin required — session with admin role OR valid API key
+ *
+ * Session tokens use the `sh3_session` cookie (httpOnly, SameSite=Lax)
+ * or the Authorization header with `Bearer sh3s_*` prefix.
+ * API keys use the Authorization header with `Bearer sh3_*` prefix.
+ */
+import { setCookie } from 'hono/cookie';
+/** Extract session token from cookie or Authorization header. */
+function extractSessionToken(c) {
+    // Cookie first
+    const cookie = c.req.raw.headers.get('cookie');
+    if (cookie) {
+        const match = cookie.match(/(?:^|;\s*)sh3_session=([^\s;]+)/);
+        if (match)
+            return match[1];
+    }
+    // Fallback to Authorization header (session tokens start with sh3s_)
+    const auth = c.req.header('Authorization');
+    if (auth?.startsWith('Bearer sh3s_'))
+        return auth.slice(7);
+    return null;
+}
+/** Extract API key from Authorization header. */
+function extractApiKey(c) {
+    const auth = c.req.header('Authorization');
+    if (auth?.startsWith('Bearer sh3_'))
+        return auth.slice(7);
+    return null;
+}
+/**
+ * Session middleware — requires a valid session on non-GET requests
+ * when auth is required. Attaches session to context variable.
+ * GET requests pass through with session attached if present.
+ */
+export function sessionAuth(sessions, settings) {
+    return async (c, next) => {
+        const token = extractSessionToken(c);
+        const session = token ? sessions.validate(token) : null;
+        // Attach session to context (may be null for guests)
+        c.set('session', session);
+        // GET/HEAD always pass through — data is filtered by the route handlers
+        if (c.req.method === 'GET' || c.req.method === 'HEAD') {
+            return next();
+        }
+        // Write operations: check if auth is required
+        const config = settings.get();
+        if (!config.auth.required) {
+            // Auth not enforced — allow all writes (open mode)
+            return next();
+        }
+        // Auth required — need a valid session for writes
+        if (!session) {
+            return c.json({ error: 'Authentication required' }, 401);
+        }
+        return next();
+    };
+}
+/**
+ * Admin middleware — requires admin session OR valid API key.
+ * Must be mounted after sessionAuth so c.get('session') is available.
+ */
+export function adminAuth(sessions, keys, settings) {
+    return async (c, next) => {
+        // When auth is disabled (--no-auth), skip admin checks entirely
+        if (settings && !settings.get().auth.required) {
+            return next();
+        }
+        // Check session first (set by sessionAuth)
+        const session = c.get('session');
+        if (session?.role === 'admin') {
+            return next();
+        }
+        // Fallback: API key (for external tools / CLI)
+        const apiKey = extractApiKey(c);
+        if (apiKey && keys.validate(apiKey)) {
+            return next();
+        }
+        return c.json({ error: 'Admin privileges required' }, 403);
+    };
+}
+/**
+ * Helper to set the session cookie on login.
+ */
+export function setSessionCookie(c, token, maxAgeSeconds) {
+    setCookie(c, 'sh3_session', token, {
+        httpOnly: true,
+        sameSite: 'Lax',
+        path: '/',
+        maxAge: maxAgeSeconds,
+    });
+}
+/**
+ * Helper to clear the session cookie on logout.
+ */
+export function clearSessionCookie(c) {
+    setCookie(c, 'sh3_session', '', {
+        httpOnly: true,
+        sameSite: 'Lax',
+        path: '/',
+        maxAge: 0,
+    });
+}

package/dist/cli.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * CLI entry for sh3-server.
+ * Usage: sh3-server [--port 3000] [--data ./data] [--dist <path>]
+ *
+ * When --dist is not provided, serves the pre-built frontend embedded
+ * in the package (../app relative to this file).
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * CLI entry for sh3-server.
+ * Usage: sh3-server [--port 3000] [--data ./data] [--dist <path>]
+ *
+ * When --dist is not provided, serves the pre-built frontend embedded
+ * in the package (../app relative to this file).
+ */
+import { parseArgs } from 'node:util';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { createServer } from './index.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const defaultDistDir = resolve(__dirname, '../app');
+const { values } = parseArgs({
+    options: {
+        port: { type: 'string', default: '3000' },
+        data: { type: 'string', default: './data' },
+        dist: { type: 'string', default: defaultDistDir },
+        'no-auth': { type: 'boolean', default: false },
+    },
+});
+const server = await createServer({
+    port: parseInt(values.port, 10),
+    dataDir: values.data,
+    distDir: values.dist,
+    noAuth: values['no-auth'],
+});
+await server.start();

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * sh3-server — lightweight Node.js server for web-hosted SH3.
+ *
+ * Serves the SH3 frontend (static files), document backend API,
+ * public registry endpoints, and auth/admin APIs. Filesystem-based
+ * storage. Three-tier auth: public / session / admin-or-apikey.
+ */
+import { Hono } from 'hono';
+import { KeyStore } from './keys.js';
+import { UserStore } from './users.js';
+import { SessionStore } from './sessions.js';
+import { SettingsStore } from './settings.js';
+export interface ServerOptions {
+    /** Port to listen on. Default: 3000 */
+    port?: number;
+    /** Directory for persistent data (docs, registry, keys). Default: './data' */
+    dataDir?: string;
+    /** Directory containing the built SH3 frontend. Default: './dist' */
+    distDir?: string;
+    /** Disable auth enforcement (for Tauri sidecar / local-owner mode). */
+    noAuth?: boolean;
+}
+export declare function createServer(options?: ServerOptions): Promise<{
+    app: Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
+    port: number;
+    dataDir: string;
+    distDir: string;
+    keys: KeyStore;
+    users: UserStore;
+    sessions: SessionStore;
+    settings: SettingsStore;
+    start(): Promise<void>;
+}>;
+export { KeyStore } from './keys.js';
+export type { ApiKey } from './keys.js';

package/dist/index.js

@@ -0,0 +1,228 @@
+/**
+ * sh3-server — lightweight Node.js server for web-hosted SH3.
+ *
+ * Serves the SH3 frontend (static files), document backend API,
+ * public registry endpoints, and auth/admin APIs. Filesystem-based
+ * storage. Three-tier auth: public / session / admin-or-apikey.
+ */
+import { Hono } from 'hono';
+import { cors } from 'hono/cors';
+import { serve } from '@hono/node-server';
+import { serveStatic } from '@hono/node-server/serve-static';
+import { createNodeWebSocket } from '@hono/node-ws';
+import { readFileSync, existsSync, renameSync } from 'node:fs';
+import { mkdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { KeyStore } from './keys.js';
+import { UserStore } from './users.js';
+import { SessionStore } from './sessions.js';
+import { SettingsStore } from './settings.js';
+import { sessionAuth, adminAuth } from './auth.js';
+import { createAuthRouter } from './routes/auth.js';
+import { createBootRouter } from './routes/boot.js';
+import { createAdminRouter } from './routes/admin.js';
+import { createDocsRouter } from './routes/docs.js';
+import { createEnvStateRouter } from './routes/env-state.js';
+import { loadPackages, scanPackages, servePackageBundles, createPackageManagementRoutes } from './packages.js';
+import { ShardRouter, adminOnly } from './shard-router.js';
+import shellShardServer from './shell-shard/index.js';
+export async function createServer(options = {}) {
+    const port = options.port ?? 3000;
+    const dataDir = options.dataDir ?? './data';
+    const distDir = options.distDir ?? './dist';
+    // Ensure data directory exists
+    mkdirSync(dataDir, { recursive: true });
+    // Migrate keys.json from legacy location (data/registry/) to data/
+    const legacyKeysPath = join(dataDir, 'registry', 'keys.json');
+    const newKeysPath = join(dataDir, 'keys.json');
+    if (existsSync(legacyKeysPath) && !existsSync(newKeysPath)) {
+        renameSync(legacyKeysPath, newKeysPath);
+        console.log('[sh3] Migrated keys.json from data/registry/ to data/');
+    }
+    // Stores
+    const keys = new KeyStore(dataDir);
+    const users = new UserStore(dataDir);
+    const settings = new SettingsStore(dataDir);
+    // --no-auth: disable auth enforcement (Tauri sidecar / local-owner mode)
+    if (options.noAuth) {
+        settings.update({ auth: { required: false, guestAllowed: true } });
+    }
+    const sessions = new SessionStore(settings.get().auth.sessionTTL);
+    const app = new Hono();
+    const { upgradeWebSocket, injectWebSocket } = createNodeWebSocket({ app });
+    const shardRouter = new ShardRouter();
+    // Factory shards call to register a WebSocket upgrade handler. The
+    // returned value is the Hono handler for `app.get(path, ..., handler)`.
+    // The onConnect callback receives both the raw WS and the Hono Context
+    // from the upgrade request, so shards can read `c.get('session')` to
+    // route the connection to the correct per-user state.
+    const wsRegister = (onConnect) => upgradeWebSocket((c) => ({
+        onOpen(_evt, ws) {
+            onConnect(ws, c);
+        },
+    }));
+    // CORS
+    app.use('*', cors({ origin: '*', credentials: true }));
+    // --- Public routes (no auth) ---
+    // Server version
+    app.get('/api/version', (c) => {
+        let version;
+        try {
+            version = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf-8')).version;
+        }
+        catch {
+            // In a SEA binary, import.meta.url is unavailable; esbuild define inlines __SEA_VERSION__.
+            version = typeof __SEA_VERSION__ !== 'undefined' ? __SEA_VERSION__ : 'unknown';
+        }
+        return c.json({ version });
+    });
+    // Boot config
+    app.route('/api/boot', createBootRouter(sessions, users, settings));
+    // Auth endpoints (login, logout, register, verify)
+    app.route('/api/auth', createAuthRouter(keys, users, sessions, settings));
+    // Document backend API
+    app.route('/api/docs', createDocsRouter(dataDir));
+    // --- Session-gated routes ---
+    app.use('/api/*', sessionAuth(sessions, settings));
+    // Environment state API (per-shard server-backed config)
+    app.route('/api/env-state', createEnvStateRouter(dataDir));
+    // Package listing (public read, writes need admin — handled by admin middleware on management routes)
+    app.get('/api/packages', (c) => {
+        const packages = scanPackages(dataDir);
+        return c.json(packages.filter(p => p.clientPath).map(p => {
+            const manifestPath = join(dataDir, 'packages', p.id, 'manifest.json');
+            let manifest = {};
+            try {
+                manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+            }
+            catch {
+                // Fall back to scanned data.
+            }
+            return {
+                id: p.id,
+                type: p.type,
+                label: p.label,
+                version: p.version,
+                bundleUrl: `/packages/${p.id}/client.js`,
+                sourceRegistry: manifest.sourceRegistry ?? '',
+                contractVersion: String(manifest.contractVersion ?? p.contractVersion ?? ''),
+                installedAt: manifest.installedAt ?? '',
+            };
+        }));
+    });
+    // Route introspection
+    app.get('/api/routes', (c) => {
+        const seen = new Set();
+        const routes = [];
+        for (const r of app.routes) {
+            const key = `${r.method} ${r.path}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            routes.push({ method: r.method, path: r.path });
+        }
+        for (const r of shardRouter.listRoutes()) {
+            const key = `${r.method} ${r.path}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            routes.push(r);
+        }
+        return c.json(routes);
+    });
+    // --- Admin-gated routes ---
+    // Admin API
+    const adminRouter = createAdminRouter(users, settings, sessions, keys, dataDir);
+    app.use('/api/admin/*', adminAuth(sessions, keys, settings));
+    app.route('/api/admin', adminRouter);
+    // Package management (install/uninstall) — admin-gated
+    app.use('/api/packages/install', adminAuth(sessions, keys, settings));
+    app.use('/api/packages/uninstall', adminAuth(sessions, keys, settings));
+    app.route('/api/packages', createPackageManagementRoutes(shardRouter, dataDir, keys, settings, wsRegister));
+    // Serve client bundles from discovered packages
+    servePackageBundles(app, dataDir);
+    // Framework built-in: shell-shard server routes.
+    //
+    // Mounted directly on the top-level Hono app (not via shardRouter) so
+    // that `@hono/node-ws` can find the WebSocket upgrade handler for
+    // `/api/shell/session`. The dynamic shardRouter dispatches requests by
+    // re-running `subApp.fetch()`, which creates a new Context per call —
+    // WS metadata stored on that inner context never propagates back to
+    // the upgrade event on the outer request, so WS upgrades silently
+    // fail. `app.route(prefix, subApp)` instead merges the sub-app's
+    // routes into the main route tree at construction time, keeping the
+    // upgrade middleware reachable.
+    {
+        const shellPkgDir = join(dataDir, 'shell-shard');
+        const shellDataDir = join(shellPkgDir, 'data');
+        mkdirSync(shellDataDir, { recursive: true });
+        const shellSubApp = new Hono();
+        await shellShardServer.routes(shellSubApp, {
+            shardId: 'shell',
+            dataDir: shellDataDir,
+            adminOnly: adminOnly(keys, settings),
+            wsRegister,
+        });
+        app.route('/api/shell', shellSubApp);
+    }
+    // Dynamic shard routes (packages). The catch-all comes after static
+    // framework mounts above so /api/shell/* is claimed first.
+    app.all('/api/:shardId/*', shardRouter.handler());
+    return {
+        app,
+        port,
+        dataDir,
+        distDir,
+        keys,
+        users,
+        sessions,
+        settings,
+        async start() {
+            // First-boot: generate admin key + admin user
+            if (keys.isEmpty()) {
+                const initial = keys.generate('Initial admin key');
+                const tempPassword = UserStore.generatePassword();
+                await users.create({
+                    username: 'admin',
+                    displayName: 'Administrator',
+                    password: tempPassword,
+                    role: 'admin',
+                });
+                console.log('');
+                console.log('╔══════════════════════════════════════════════════════════╗');
+                console.log('║  SH3 First Boot                                        ║');
+                console.log('╠══════════════════════════════════════════════════════════╣');
+                console.log(`║  API key:  ${initial.key}  ║`);
+                console.log(`║  Admin:    admin / ${tempPassword.padEnd(37)}║`);
+                console.log('║  Change the admin password immediately.                 ║');
+                console.log('╚══════════════════════════════════════════════════════════╝');
+                console.log('');
+            }
+            await loadPackages(shardRouter, dataDir, keys, settings, wsRegister);
+            // Periodic session cleanup (every 15 minutes)
+            setInterval(() => sessions.cleanup(), 15 * 60 * 1000);
+            // API 404
+            app.all('/api/*', (c) => c.json({ error: 'Not found' }, 404));
+            // Static assets
+            app.use('/*', serveStatic({ root: distDir }));
+            app.get('/', serveStatic({ root: distDir, path: 'index.html' }));
+            // 404 fallback
+            // In a SEA binary, import.meta.url is unavailable; esbuild define inlines __SEA_404_HTML__.
+            let page404;
+            try {
+                const staticDir = join(dirname(fileURLToPath(import.meta.url)), '..', 'static');
+                page404 = readFileSync(join(staticDir, '404.html'), 'utf-8');
+            }
+            catch {
+                page404 = typeof __SEA_404_HTML__ !== 'undefined' ? __SEA_404_HTML__ : '<html><body>404 Not Found</body></html>';
+            }
+            app.all('*', (c) => c.html(page404, 404));
+            const server = serve({ fetch: app.fetch, port }, () => {
+                console.log(`sh3-server listening on http://localhost:${port}`);
+            });
+            injectWebSocket(server);
+        },
+    };
+}
+export { KeyStore } from './keys.js';

package/dist/keys.d.ts

@@ -0,0 +1,33 @@
+/**
+ * API key management — generate, validate, list, revoke.
+ *
+ * Keys are stored in {dataDir}/keys.json. Each key has an id
+ * (short identifier for display/revocation), the full key value (used
+ * for auth), a label, and creation timestamp.
+ */
+export interface ApiKey {
+    /** Short id for display and revocation. */
+    id: string;
+    /** The full bearer token value. */
+    key: string;
+    /** Human-readable label. */
+    label: string;
+    /** ISO timestamp of creation. */
+    createdAt: string;
+}
+export declare class KeyStore {
+    #private;
+    constructor(dataDir: string);
+    /** Validate a bearer token. Returns true if the key exists. */
+    validate(token: string): boolean;
+    /** List all keys (returns id, label, createdAt — never the full key). */
+    list(): Omit<ApiKey, 'key'>[];
+    /** List all keys including full key values (admin only). */
+    listFull(): ApiKey[];
+    /** Generate a new API key. Returns the full key (only shown once). */
+    generate(label: string): ApiKey;
+    /** Revoke a key by id. Returns true if found and removed. */
+    revoke(id: string): boolean;
+    /** True if no keys exist (first boot). */
+    isEmpty(): boolean;
+}

package/dist/keys.js

@@ -0,0 +1,68 @@
+/**
+ * API key management — generate, validate, list, revoke.
+ *
+ * Keys are stored in {dataDir}/keys.json. Each key has an id
+ * (short identifier for display/revocation), the full key value (used
+ * for auth), a label, and creation timestamp.
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { randomBytes } from 'node:crypto';
+export class KeyStore {
+    #path;
+    #keys = [];
+    constructor(dataDir) {
+        this.#path = join(dataDir, 'keys.json');
+        this.#load();
+    }
+    #load() {
+        if (existsSync(this.#path)) {
+            try {
+                this.#keys = JSON.parse(readFileSync(this.#path, 'utf-8'));
+            }
+            catch {
+                this.#keys = [];
+            }
+        }
+    }
+    #save() {
+        const dir = dirname(this.#path);
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(this.#path, JSON.stringify(this.#keys, null, 2));
+    }
+    /** Validate a bearer token. Returns true if the key exists. */
+    validate(token) {
+        return this.#keys.some((k) => k.key === token);
+    }
+    /** List all keys (returns id, label, createdAt — never the full key). */
+    list() {
+        return this.#keys.map(({ id, label, createdAt }) => ({ id, label, createdAt }));
+    }
+    /** List all keys including full key values (admin only). */
+    listFull() {
+        return this.#keys.map((k) => ({ ...k }));
+    }
+    /** Generate a new API key. Returns the full key (only shown once). */
+    generate(label) {
+        const id = randomBytes(4).toString('hex');
+        const key = `sh3_${randomBytes(32).toString('hex')}`;
+        const entry = { id, key, label, createdAt: new Date().toISOString() };
+        this.#keys.push(entry);
+        this.#save();
+        return entry;
+    }
+    /** Revoke a key by id. Returns true if found and removed. */
+    revoke(id) {
+        const before = this.#keys.length;
+        this.#keys = this.#keys.filter((k) => k.id !== id);
+        if (this.#keys.length < before) {
+            this.#save();
+            return true;
+        }
+        return false;
+    }
+    /** True if no keys exist (first boot). */
+    isEmpty() {
+        return this.#keys.length === 0;
+    }
+}

package/dist/packages.d.ts

@@ -0,0 +1,38 @@
+import { Hono } from 'hono';
+import type { KeyStore } from './keys.js';
+import type { SettingsStore } from './settings.js';
+import { ShardRouter } from './shard-router.js';
+import type { MountContext } from './shard-router.js';
+/** Type of the `wsRegister` factory field from MountContext. */
+type WsRegister = MountContext['wsRegister'];
+export interface DiscoveredPackage {
+    id: string;
+    type: string;
+    label: string;
+    version: string;
+    contractVersion: number;
+    clientPath?: string;
+    serverPath?: string;
+}
+/**
+ * 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 declare function loadPackages(shardRouter: ShardRouter, dataDir: string, keys: KeyStore, settings: SettingsStore, wsRegister: WsRegister): Promise<DiscoveredPackage[]>;
+/**
+ * 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 declare function scanPackages(dataDir: string): DiscoveredPackage[];
+/**
+ * Register `GET /packages/:id/client.js` to serve client bundles from disk.
+ */
+export declare function servePackageBundles(app: Hono, dataDir: string): void;
+/**
+ * Returns a Hono router with POST /install and POST /uninstall.
+ * Protected by the blanket `/api/*` auth middleware already applied upstream.
+ */
+export declare function createPackageManagementRoutes(shardRouter: ShardRouter, dataDir: string, keys: KeyStore, settings: SettingsStore, wsRegister: WsRegister): Hono;
+export {};