sh3-server 0.8.1 → 0.8.2

package/dist/keys.js

@@ -1,68 +1,191 @@
 /**
- * API key management — generate, validate, list, revoke.
+ * Unified API key store — admin, user-tenant, and connector-bound keys.
  *
- * 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.
+ * Layout on disk:
+ *   <dataDir>/admin-keys.json            — tenantId: null rows only
+ *   <dataDir>/users/<tenantId>/__system__/keys.json — user-tenant rows
+ *
+ * Legacy migration: a pre-existing <dataDir>/keys.json is treated as admin
+ * keys and moved to admin-keys.json on first load, with the original renamed
+ * to keys.json.legacy.
  */
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
-import { join, dirname } from 'node:path';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, renameSync, } from 'node:fs';
+import { dirname, join } from 'node:path';
 import { randomBytes } from 'node:crypto';
+function strip(k) {
+    const { key: _drop, ...rest } = k;
+    return rest;
+}
 export class KeyStore {
-    #path;
-    #keys = [];
+    #dataDir;
+    #admin = [];
+    #byTenant = new Map();
     constructor(dataDir) {
-        this.#path = join(dataDir, 'keys.json');
-        this.#load();
+        this.#dataDir = dataDir;
+        this.#migrateLegacy();
+        this.#loadAdmin();
+        this.#loadAllTenants();
+    }
+    // ---------- public API ----------
+    generate(input) {
+        const id = randomBytes(4).toString('hex');
+        const key = `sh3_${randomBytes(32).toString('hex')}`;
+        const row = {
+            id,
+            key,
+            label: input.label,
+            tenantId: input.tenantId,
+            ownerUserId: input.ownerUserId,
+            mintedByShardId: input.mintedByShardId,
+            scopes: [...input.scopes],
+            connectorId: input.connectorId,
+            createdAt: new Date().toISOString(),
+            expiresAt: input.expiresAt,
+        };
+        if (row.tenantId === null) {
+            this.#admin.push(row);
+            this.#saveAdmin();
+        }
+        else {
+            const bucket = this.#byTenant.get(row.tenantId) ?? [];
+            bucket.push(row);
+            this.#byTenant.set(row.tenantId, bucket);
+            this.#saveTenant(row.tenantId);
+        }
+        return { ...row, scopes: [...row.scopes] };
+    }
+    resolve(token) {
+        const now = Date.now();
+        const match = (row) => {
+            if (row.key !== token)
+                return false;
+            if (row.expiresAt && Date.parse(row.expiresAt) <= now)
+                return false;
+            return true;
+        };
+        const adminHit = this.#admin.find(match);
+        if (adminHit)
+            return adminHit;
+        for (const bucket of this.#byTenant.values()) {
+            const hit = bucket.find(match);
+            if (hit)
+                return hit;
+        }
+        return null;
+    }
+    listForTenant(tenantId) {
+        return (this.#byTenant.get(tenantId) ?? []).map(strip);
+    }
+    listForShard(tenantId, shardId) {
+        return this.listForTenant(tenantId).filter((k) => k.mintedByShardId === shardId);
+    }
+    listAdmin() {
+        return this.#admin.map(strip);
+    }
+    listAll() {
+        const out = this.#admin.map(strip);
+        for (const bucket of this.#byTenant.values())
+            out.push(...bucket.map(strip));
+        return out;
+    }
+    revoke(tenantId, id) {
+        if (tenantId === null) {
+            const idx = this.#admin.findIndex((k) => k.id === id);
+            if (idx < 0)
+                return null;
+            const [removed] = this.#admin.splice(idx, 1);
+            this.#saveAdmin();
+            return strip(removed);
+        }
+        const bucket = this.#byTenant.get(tenantId);
+        if (!bucket)
+            return null;
+        const idx = bucket.findIndex((k) => k.id === id);
+        if (idx < 0)
+            return null;
+        const [removed] = bucket.splice(idx, 1);
+        this.#saveTenant(tenantId);
+        return strip(removed);
     }
-    #load() {
-        if (existsSync(this.#path)) {
+    isEmpty() {
+        return this.#admin.length === 0;
+    }
+    // ---------- persistence ----------
+    #adminPath() {
+        return join(this.#dataDir, 'admin-keys.json');
+    }
+    #tenantPath(tenantId) {
+        return join(this.#dataDir, 'users', tenantId, '__system__', 'keys.json');
+    }
+    #loadAdmin() {
+        const p = this.#adminPath();
+        if (!existsSync(p))
+            return;
+        try {
+            const raw = JSON.parse(readFileSync(p, 'utf-8'));
+            this.#admin.push(...raw);
+        }
+        catch {
+            // Corrupt admin file — leave empty; the next generate() overwrites.
+        }
+    }
+    #loadAllTenants() {
+        const usersDir = join(this.#dataDir, 'users');
+        if (!existsSync(usersDir))
+            return;
+        for (const entry of readdirSync(usersDir, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const tenantId = entry.name;
+            const file = this.#tenantPath(tenantId);
+            if (!existsSync(file))
+                continue;
             try {
-                this.#keys = JSON.parse(readFileSync(this.#path, 'utf-8'));
+                const raw = JSON.parse(readFileSync(file, 'utf-8'));
+                this.#byTenant.set(tenantId, raw);
             }
             catch {
-                this.#keys = [];
+                this.#byTenant.set(tenantId, []);
             }
         }
     }
-    #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 }));
+    #saveAdmin() {
+        const p = this.#adminPath();
+        mkdirSync(dirname(p), { recursive: true });
+        writeFileSync(p, JSON.stringify(this.#admin, null, 2));
     }
-    /** List all keys including full key values (admin only). */
-    listFull() {
-        return this.#keys.map((k) => ({ ...k }));
+    #saveTenant(tenantId) {
+        const bucket = this.#byTenant.get(tenantId) ?? [];
+        const p = this.#tenantPath(tenantId);
+        mkdirSync(dirname(p), { recursive: true });
+        writeFileSync(p, JSON.stringify(bucket, null, 2));
     }
-    /** 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;
+    #migrateLegacy() {
+        const legacyPath = join(this.#dataDir, 'keys.json');
+        const adminPath = this.#adminPath();
+        if (!existsSync(legacyPath) || existsSync(adminPath))
+            return;
+        try {
+            const legacy = JSON.parse(readFileSync(legacyPath, 'utf-8'));
+            const migrated = legacy.map((row) => ({
+                ...row,
+                tenantId: null,
+                ownerUserId: null,
+                mintedByShardId: null,
+                scopes: ['admin:*'],
+            }));
+            mkdirSync(dirname(adminPath), { recursive: true });
+            writeFileSync(adminPath, JSON.stringify(migrated, null, 2));
+            renameSync(legacyPath, legacyPath + '.legacy');
+        }
+        catch {
+            // If migration fails, leave everything alone; admin can investigate.
         }
-        return false;
     }
-    /** True if no keys exist (first boot). */
-    isEmpty() {
-        return this.#keys.length === 0;
+    // ---------- legacy compat ----------
+    /** @deprecated use resolve() — kept until all callers migrate. */
+    validate(token) {
+        const hit = this.resolve(token);
+        return !!hit && hit.scopes.includes('admin:*');
     }
 }

package/dist/packages.d.ts

@@ -5,6 +5,8 @@ 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'];
+/** Type of the `documentBackend` field from MountContext. */
+type DocumentBackend = MountContext['documentBackend'];
 export interface DiscoveredPackage {
     id: string;
     type: string;
@@ -19,7 +21,7 @@ export interface DiscoveredPackage {
  * 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[]>;
+export declare function loadPackages(shardRouter: ShardRouter, dataDir: string, keys: KeyStore, settings: SettingsStore, wsRegister: WsRegister, documentBackend: DocumentBackend): Promise<DiscoveredPackage[]>;
 /**
  * Re-scan `<dataDir>/packages/` and return metadata for all valid packages.
  * Unlike `loadPackages`, this does NOT mount server routes — it only reads
@@ -52,5 +54,5 @@ export declare function validateRequiredShards(manifest: Record<string, unknown>
  * 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, frameworkShardIds?: string[]): Hono;
+export declare function createPackageManagementRoutes(shardRouter: ShardRouter, dataDir: string, keys: KeyStore, settings: SettingsStore, wsRegister: WsRegister, documentBackend: DocumentBackend, frameworkShardIds?: string[]): Hono;
 export {};

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) {
+export async function loadPackages(shardRouter, dataDir, keys, settings, wsRegister, documentBackend) {
     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 });
+                    await shardRouter.mount(manifest.id, serverJs, { pkgDir, keys, settings, wsRegister, documentBackend });
                 }
                 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, frameworkShardIds = []) {
+export function createPackageManagementRoutes(shardRouter, dataDir, keys, settings, wsRegister, documentBackend, 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 });
+                await shardRouter.mount(id, join(pkgDir, 'server.js'), { pkgDir, keys, settings, wsRegister, documentBackend });
             }
             catch (err) {
                 // Roll back entire install — broken server bundle must not be half-installed

package/dist/routes/admin.js

@@ -99,7 +99,11 @@ export function createAdminRouter(users, settings, sessions, keys, dataDir) {
     });
     // --- API Keys ---
     router.get('/keys', (c) => {
-        return c.json(keys.listFull());
+        return c.json(keys.listAdmin());
+    });
+    /** Read-only audit endpoint — every key across all tenants and admin. */
+    router.get('/keys/all', (c) => {
+        return c.json(keys.listAll());
     });
     router.post('/keys', async (c) => {
         let body;
@@ -113,12 +117,12 @@ export function createAdminRouter(users, settings, sessions, keys, dataDir) {
         if (!label) {
             return c.json({ error: 'Label required' }, 400);
         }
-        const key = keys.generate(label);
+        const key = keys.generate({ label, tenantId: null, ownerUserId: null, mintedByShardId: null, scopes: ['admin:*'] });
         return c.json(key, 201);
     });
     router.delete('/keys/:id', (c) => {
         const id = c.req.param('id');
-        if (!keys.revoke(id))
+        if (!keys.revoke(null, id))
             return c.json({ error: 'Key not found' }, 404);
         return c.body(null, 204);
     });

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,164 @@
+/**
+ * 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,
+            connectorId: body.connectorId,
+            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,
+            connectorId: entry.connectorId,
+            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,9 @@
+/**
+ * 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';
+export declare function scopeRequired(scope: string): MiddlewareHandler;
+export declare const tenantRequired: MiddlewareHandler;

package/dist/scope.js

@@ -0,0 +1,25 @@
+/**
+ * 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();
+};

package/dist/shard-router.d.ts

@@ -6,6 +6,8 @@ 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;
     /**
      * Register a WebSocket upgrade handler on a path under this shard's
      * route prefix. The returned value is a Hono middleware handler that
@@ -45,8 +47,13 @@ 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;
+/**
+ * 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.