sh3-server 0.8.1 → 0.9.0

package/dist/index.js

@@ -19,13 +19,18 @@ import { UserStore } from './users.js';
 import { SessionStore } from './sessions.js';
 import { SettingsStore } from './settings.js';
 import { sessionAuth, adminAuth } from './auth.js';
+import { resolveCaller } from './caller.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 { createTenantDocStore } from './doc-store/index.js';
 import { createEnvStateRouter } from './routes/env-state.js';
+import { createKeysRouter } from './routes/keys.js';
 import { loadPackages, scanPackages, servePackageBundles, createPackageManagementRoutes } from './packages.js';
+import { removeLegacyGrants } from './migrations/sync-grants.js';
 import { ShardRouter, adminOnly } from './shard-router.js';
+import { scopeRequired, tenantRequired } from './scope.js';
 import { registerTenantFsRoutes } from './tenant-fs/index.js';
 import shellShardServer from './shell-shard/index.js';
 export async function createServer(options = {}) {
@@ -109,12 +114,21 @@ export async function createServer(options = {}) {
     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));
+    app.use('/api/*', resolveCaller(keys));
+    // Document backend API — gated by sessionAuth + resolveCaller (mounted above).
+    // The router itself enforces tenantParamMatch and the __-prefix reservation.
+    // Settings is threaded so tenantParamMatch respects open / no-auth mode.
+    const docStore = createTenantDocStore(dataDir);
+    app.route('/api/docs', createDocsRouter(docStore, settings));
     // Environment state API (per-shard server-backed config)
     app.route('/api/env-state', createEnvStateRouter(dataDir));
+    // User-tenant key management (list/revoke). Mint lives at /api/shards-keys.
+    app.route('/api/keys', createKeysRouter(keys, async (event) => {
+        // Broadcast will be wired in Task 10 once the shell has a consumer.
+        console.log(`[sh3] key revoked: tenant=${event.tenantId} id=${event.id}`);
+    }));
     // Package listing (public read, writes need admin — handled by admin middleware on management routes)
     app.get('/api/packages', (c) => {
         const packages = scanPackages(dataDir);
@@ -168,7 +182,7 @@ export async function createServer(options = {}) {
     app.use('/api/packages/install', adminAuth(sessions, keys, settings));
     app.use('/api/packages/uninstall', adminAuth(sessions, keys, settings));
     const frameworkShardIds = ['__sh3core__', 'shell', 'sh3-store', 'sh3-admin'];
-    app.route('/api/packages', createPackageManagementRoutes(shardRouter, dataDir, keys, settings, wsRegister, frameworkShardIds));
+    app.route('/api/packages', createPackageManagementRoutes(shardRouter, dataDir, keys, settings, wsRegister, docStore, frameworkShardIds));
     // Serve client bundles from discovered packages
     servePackageBundles(app, dataDir, settings);
     // Framework built-in: shell-shard server routes.
@@ -190,7 +204,10 @@ export async function createServer(options = {}) {
         await shellShardServer.routes(shellSubApp, {
             shardId: 'shell',
             dataDir: shellDataDir,
+            permissions: [],
             adminOnly: adminOnly(keys, settings),
+            scopeRequired,
+            tenantRequired,
             wsRegister,
         });
         app.route('/api/shell', shellSubApp);
@@ -215,10 +232,12 @@ export async function createServer(options = {}) {
         users,
         sessions,
         settings,
+        docStore,
         async start() {
+            removeLegacyGrants(dataDir);
             // First-boot: generate admin key + admin user
             if (keys.isEmpty()) {
-                const initial = keys.generate('Initial admin key');
+                const initial = keys.generate({ label: 'Initial admin key', tenantId: null, ownerUserId: null, mintedByShardId: null, scopes: ['admin:*'] });
                 const tempPassword = UserStore.generatePassword();
                 await users.create({
                     username: 'admin',
@@ -246,7 +265,7 @@ export async function createServer(options = {}) {
                     console.log(`[sh3] Seeded official registry: ${registryUrl}`);
                 }
             }
-            await loadPackages(shardRouter, dataDir, keys, settings, wsRegister);
+            await loadPackages(shardRouter, dataDir, keys, settings, wsRegister, docStore);
             // Periodic session cleanup (every 15 minutes)
             setInterval(() => sessions.cleanup(), 15 * 60 * 1000);
             // API 404
@@ -269,6 +288,14 @@ export async function createServer(options = {}) {
                 console.log(`sh3-server listening on http://localhost:${port}`);
             });
             injectWebSocket(server);
+            const shutdown = async (sig) => {
+                console.log(`[sh3] received ${sig}, tearing down shards...`);
+                await shardRouter.unmountAll();
+                server.close();
+                process.exit(0);
+            };
+            process.on('SIGINT', () => { void shutdown('SIGINT'); });
+            process.on('SIGTERM', () => { void shutdown('SIGTERM'); });
         },
     };
 }

package/dist/keys.d.ts

@@ -1,33 +1,49 @@
 /**
- * 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.
  */
 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. */
+    tenantId: string | null;
+    ownerUserId: string | null;
+    mintedByShardId: string | null;
+    scopes: string[];
+    peerRole?: 'primary' | 'replica';
+    peerId?: string;
     createdAt: string;
+    expiresAt?: string;
+}
+export type ApiKeyPublic = Omit<ApiKey, 'key'>;
+export interface GenerateInput {
+    label: string;
+    tenantId: string | null;
+    ownerUserId: string | null;
+    mintedByShardId: string | null;
+    scopes: string[];
+    peerRole?: 'primary' | 'replica';
+    peerId?: string;
+    expiresAt?: 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). */
+    generate(input: GenerateInput): ApiKey;
+    resolve(token: string): ApiKey | null;
+    listForTenant(tenantId: string): ApiKeyPublic[];
+    listForShard(tenantId: string, shardId: string): ApiKeyPublic[];
+    listAdmin(): ApiKeyPublic[];
+    listAll(): ApiKeyPublic[];
+    revoke(tenantId: string | null, id: string): ApiKeyPublic | null;
     isEmpty(): boolean;
+    /** @deprecated use resolve() — kept until all callers migrate. */
+    validate(token: string): boolean;
 }

package/dist/keys.js

@@ -1,68 +1,206 @@
 /**
- * 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],
+            peerRole: input.peerRole,
+            peerId: input.peerId,
+            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'));
+            const dirty = raw.some((row) => 'connectorId' in row);
+            const cleaned = raw.map((row) => {
+                const { connectorId: _drop, ...rest } = row;
+                return rest;
+            });
+            this.#admin.push(...cleaned);
+            if (dirty)
+                this.#saveAdmin();
+        }
+        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'));
+                const dirty = raw.some((row) => 'connectorId' in row);
+                const cleaned = raw.map((row) => {
+                    const { connectorId: _drop, ...rest } = row;
+                    return rest;
+                });
+                this.#byTenant.set(tenantId, cleaned);
+                if (dirty)
+                    this.#saveTenant(tenantId);
             }
             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/migrations/sync-grants.d.ts

@@ -0,0 +1,7 @@
+/**
+ * ADR-019 §11.2: retire the legacy `grants/` namespace under the reserved
+ * `__sync__` shard id for every tenant. Idempotent; safe to run on every
+ * boot. Other `__sync__/` subdirectories are out of scope here — they
+ * disappear when the sync runtime is rebuilt in sh3-server.
+ */
+export declare function removeLegacyGrants(dataDir: string): void;

package/dist/migrations/sync-grants.js

@@ -0,0 +1,27 @@
+/**
+ * ADR-019 §11.2: retire the legacy `grants/` namespace under the reserved
+ * `__sync__` shard id for every tenant. Idempotent; safe to run on every
+ * boot. Other `__sync__/` subdirectories are out of scope here — they
+ * disappear when the sync runtime is rebuilt in sh3-server.
+ */
+import { existsSync, readdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+export function removeLegacyGrants(dataDir) {
+    const docsDir = join(dataDir, 'docs');
+    if (!existsSync(docsDir))
+        return;
+    const tenants = readdirSync(docsDir, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name);
+    let removed = 0;
+    for (const tenant of tenants) {
+        const grants = join(docsDir, tenant, '__sync__', 'grants');
+        if (existsSync(grants)) {
+            rmSync(grants, { recursive: true, force: true });
+            removed += 1;
+        }
+    }
+    if (removed > 0) {
+        console.log(`[sh3] migration: removed legacy __sync__/grants/ for ${removed} tenant(s)`);
+    }
+}

package/dist/packages.d.ts

@@ -3,6 +3,7 @@ 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';
+import type { TenantDocStore } from './doc-store/index.js';
 /** Type of the `wsRegister` factory field from MountContext. */
 type WsRegister = MountContext['wsRegister'];
 export interface DiscoveredPackage {
@@ -19,7 +20,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, docStore: TenantDocStore): 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 +53,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, docStore: TenantDocStore, 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, docStore) {
     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, docStore });
                 }
                 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, docStore, 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, docStore });
             }
             catch (err) {
                 // Roll back entire install — broken server bundle must not be half-installed
@@ -297,7 +297,7 @@ export function createPackageManagementRoutes(shardRouter, dataDir, keys, settin
             return c.json({ error: `Package "${id}" not found` }, 404);
         }
         // Unmount server routes immediately
-        shardRouter.unmount(id);
+        await shardRouter.unmount(id);
         // Remove code files
         rmSync(manifestPath, { force: true });
         const clientPath = join(pkgDir, 'client.js');

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

@@ -1,16 +1,20 @@
 /**
  * Document backend API routes.
  *
- * Maps the DocumentBackend interface to HTTP endpoints backed by the
- * local filesystem. Files are stored at {dataDir}/docs/{tenant}/{shard}/{path}.
+ * Delegates every read/write/list/delete to the TenantDocStore, which owns
+ * the metadata-sidecar write pipeline (version bump, syncMode cache, tick
+ * advance, conflict bucket). This router is intentionally thin: it validates
+ * auth and path shape, then calls the store.
  *
- * GET    /api/docs/:tenant/_shards         → listAllShards
- * GET    /api/docs/:tenant/_all            → listAllDocuments
+ * GET    /api/docs/:tenant/_shards         → listAll (shard ids)
+ * GET    /api/docs/:tenant/_all            → listAll
  * GET    /api/docs/:tenant/:shard          → list
  * GET    /api/docs/:tenant/:shard/*path    → read
  * HEAD   /api/docs/:tenant/:shard/*path    → exists
- * PUT    /api/docs/:tenant/:shard/*path    → write (auth required)
- * DELETE /api/docs/:tenant/:shard/*path    → delete (auth required)
+ * PUT    /api/docs/:tenant/:shard/*path    → write
+ * DELETE /api/docs/:tenant/:shard/*path    → delete
  */
 import { Hono } from 'hono';
-export declare function createDocsRouter(dataDir: string): Hono;
+import type { SettingsStore } from '../settings.js';
+import type { TenantDocStore } from '../doc-store/index.js';
+export declare function createDocsRouter(store: TenantDocStore, settings?: SettingsStore): Hono;