sh3-server 0.7.5 → 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
@@ -28,11 +30,29 @@ export declare function loadPackages(shardRouter: ShardRouter, dataDir: string,
 export declare function scanPackages(dataDir: string): DiscoveredPackage[];
 /**
  * Register `GET /packages/:id/client.js` to serve client bundles from disk.
+ * The `Cache-Control` header is read from settings on every request:
+ *  - cacheMaxAge === 0 → `no-store`
+ *  - otherwise → `public, max-age=<n>` (never `immutable`)
  */
-export declare function servePackageBundles(app: Hono, dataDir: string): void;
+export declare function servePackageBundles(app: Hono, dataDir: string, settings: SettingsStore): void;
+export interface MissingShardsResult {
+    missing: Array<{
+        id: string;
+    }>;
+}
+/**
+ * Check an uploaded manifest's `requiredShards` against the set of shard ids
+ * already known to the server (framework shards + installed shard/combo
+ * packages + shards present in the current upload for combo bundles).
+ *
+ * Returns `{ missing: [] }` for shard-only packages or when all requirements
+ * are satisfied. The shape of `missing` entries is deliberately extensible
+ * (future version-mismatch entries can add a `versionMismatch: true` flag).
+ */
+export declare function validateRequiredShards(manifest: Record<string, unknown>, knownShards: Set<string>): MissingShardsResult;
 /**
  * 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 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);
@@ -138,8 +138,11 @@ export function scanPackages(dataDir) {
 // ---------------------------------------------------------------------------
 /**
  * Register `GET /packages/:id/client.js` to serve client bundles from disk.
+ * The `Cache-Control` header is read from settings on every request:
+ *  - cacheMaxAge === 0 → `no-store`
+ *  - otherwise → `public, max-age=<n>` (never `immutable`)
  */
-export function servePackageBundles(app, dataDir) {
+export function servePackageBundles(app, dataDir, settings) {
     app.get('/packages/:id/client.js', (c) => {
         const id = c.req.param('id');
         if (!isValidId(id)) {
@@ -149,13 +152,40 @@ export function servePackageBundles(app, dataDir) {
         if (!existsSync(filePath)) {
             return c.json({ error: 'Client bundle not found' }, 404);
         }
+        const maxAge = settings.get().packages.cacheMaxAge;
+        const cacheControl = maxAge === 0 ? 'no-store' : `public, max-age=${maxAge}`;
         const content = readFileSync(filePath, 'utf-8');
         return c.body(content, 200, {
             'Content-Type': 'application/javascript',
-            'Cache-Control': 'public, max-age=31536000, immutable',
+            'Cache-Control': cacheControl,
         });
     });
 }
+/**
+ * Check an uploaded manifest's `requiredShards` against the set of shard ids
+ * already known to the server (framework shards + installed shard/combo
+ * packages + shards present in the current upload for combo bundles).
+ *
+ * Returns `{ missing: [] }` for shard-only packages or when all requirements
+ * are satisfied. The shape of `missing` entries is deliberately extensible
+ * (future version-mismatch entries can add a `versionMismatch: true` flag).
+ */
+export function validateRequiredShards(manifest, knownShards) {
+    const type = manifest.type;
+    if (type !== 'app' && type !== 'combo')
+        return { missing: [] };
+    const required = manifest.requiredShards;
+    if (!Array.isArray(required))
+        return { missing: [] };
+    const missing = [];
+    for (const id of required) {
+        if (typeof id !== 'string')
+            continue;
+        if (!knownShards.has(id))
+            missing.push({ id });
+    }
+    return { missing };
+}
 // ---------------------------------------------------------------------------
 // Package management routes (install / uninstall)
 // ---------------------------------------------------------------------------
@@ -163,7 +193,7 @@ export function servePackageBundles(app, dataDir) {
  * 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) {
+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();
@@ -189,6 +219,37 @@ export function createPackageManagementRoutes(shardRouter, dataDir, keys, settin
         if (typeof manifest.version !== 'string' || !manifest.version) {
             return c.json({ error: 'Missing "version" in manifest' }, 400);
         }
+        // requiredShards guard — reject apps whose shard deps are not on the server.
+        const installedShardIds = [];
+        const pkgsDir = join(dataDir, 'packages');
+        if (existsSync(pkgsDir)) {
+            for (const entry of readdirSync(pkgsDir, { withFileTypes: true })) {
+                if (!entry.isDirectory())
+                    continue;
+                const otherManifestPath = join(pkgsDir, entry.name, 'manifest.json');
+                if (!existsSync(otherManifestPath))
+                    continue;
+                try {
+                    const other = JSON.parse(readFileSync(otherManifestPath, 'utf-8'));
+                    if ((other.type === 'shard' || other.type === 'combo') && typeof other.id === 'string') {
+                        installedShardIds.push(other.id);
+                    }
+                }
+                catch { /* skip malformed manifest */ }
+            }
+        }
+        const knownShards = new Set([
+            ...frameworkShardIds,
+            ...installedShardIds,
+        ]);
+        // Combo uploads contribute their own shard to the known set (the shard id equals the combo id).
+        if (manifest.type === 'combo' && typeof manifest.id === 'string') {
+            knownShards.add(manifest.id);
+        }
+        const { missing } = validateRequiredShards(manifest, knownShards);
+        if (missing.length > 0) {
+            return c.json({ code: 'missing-shards', missing }, 409);
+        }
         const pkgDir = join(dataDir, 'packages', id);
         mkdirSync(pkgDir, { recursive: true });
         // Write manifest
@@ -206,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/docs.d.ts

@@ -4,6 +4,8 @@
  * 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/_shards         → listAllShards
+ * GET    /api/docs/:tenant/_all            → listAllDocuments
  * GET    /api/docs/:tenant/:shard          → list
  * GET    /api/docs/:tenant/:shard/*path    → read
  * HEAD   /api/docs/:tenant/:shard/*path    → exists

package/dist/routes/docs.js

@@ -4,6 +4,8 @@
  * 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/_shards         → listAllShards
+ * GET    /api/docs/:tenant/_all            → listAllDocuments
  * GET    /api/docs/:tenant/:shard          → list
  * GET    /api/docs/:tenant/:shard/*path    → read
  * HEAD   /api/docs/:tenant/:shard/*path    → exists
@@ -45,6 +47,34 @@ export function createDocsRouter(dataDir) {
         }
         return results;
     }
+    // List all shard ids that have content for a tenant.
+    router.get('/:tenant/_shards', (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);
+    });
+    // Tenant-wide document list with shardId attached on each entry.
+    router.get('/:tenant/_all', (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);
+    });
     // List documents for a tenant/shard
     router.get('/:tenant/:shard', (c) => {
         const { tenant, shard } = c.req.param();

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;