sh3-server 0.7.5 → 0.8.2

package/dist/tenant-fs/http.js

@@ -0,0 +1,109 @@
+/**
+ * Tenant FS HTTP API — mounts /api/fs/list, /api/fs/stat, /api/fs/read.
+ *
+ * Gated by sessionRequired; scope is the caller's own documentsRoot.
+ * Read-only. Writes are out of scope for this iteration.
+ */
+import { readdir, stat, readFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { documentsRoot } from './paths.js';
+import { resolveTenantPath, TenantPathEscapeError } from './resolve.js';
+import { makeSessionRequired } from './session-required.js';
+function userIdFromContext(c) {
+    const session = c.get('session') ?? c.env?.session;
+    if (!session?.userId)
+        throw new Error('sessionRequired missing before handler');
+    return session.userId;
+}
+export function registerTenantFsRoutes(app, ctx) {
+    const sessionRequired = makeSessionRequired(ctx.settings);
+    app.get('/api/fs/list', sessionRequired, async (c) => {
+        const rel = c.req.query('path') ?? '';
+        const root = documentsRoot(ctx.dataDir, userIdFromContext(c), ctx.rootBase);
+        let abs;
+        try {
+            abs = await resolveTenantPath(root, rel);
+        }
+        catch (err) {
+            if (err instanceof TenantPathEscapeError)
+                return c.json({ error: 'forbidden' }, 403);
+            throw err;
+        }
+        let names;
+        try {
+            names = await readdir(abs);
+        }
+        catch (err) {
+            if (err?.code === 'ENOENT')
+                return c.json({ error: 'not found' }, 404);
+            if (err?.code === 'ENOTDIR')
+                return c.json({ error: 'not a directory' }, 400);
+            throw err;
+        }
+        const entries = await Promise.all(names.map(async (name) => {
+            const s = await stat(`${abs}/${name}`);
+            return {
+                name,
+                kind: s.isDirectory() ? 'dir' : 'file',
+                size: s.size,
+                mtime: s.mtimeMs,
+            };
+        }));
+        return c.json({ entries });
+    });
+    app.get('/api/fs/stat', sessionRequired, async (c) => {
+        const rel = c.req.query('path') ?? '';
+        const root = documentsRoot(ctx.dataDir, userIdFromContext(c), ctx.rootBase);
+        let abs;
+        try {
+            abs = await resolveTenantPath(root, rel);
+        }
+        catch (err) {
+            if (err instanceof TenantPathEscapeError)
+                return c.json({ error: 'forbidden' }, 403);
+            throw err;
+        }
+        try {
+            const s = await stat(abs);
+            return c.json({
+                name: basename(abs),
+                kind: s.isDirectory() ? 'dir' : 'file',
+                size: s.size,
+                mtime: s.mtimeMs,
+            });
+        }
+        catch (err) {
+            if (err?.code === 'ENOENT')
+                return c.json({ error: 'not found' }, 404);
+            throw err;
+        }
+    });
+    app.get('/api/fs/read', sessionRequired, async (c) => {
+        const rel = c.req.query('path') ?? '';
+        const root = documentsRoot(ctx.dataDir, userIdFromContext(c), ctx.rootBase);
+        let abs;
+        try {
+            abs = await resolveTenantPath(root, rel);
+        }
+        catch (err) {
+            if (err instanceof TenantPathEscapeError)
+                return c.json({ error: 'forbidden' }, 403);
+            throw err;
+        }
+        let s;
+        try {
+            s = await stat(abs);
+        }
+        catch (err) {
+            if (err?.code === 'ENOENT')
+                return c.json({ error: 'not found' }, 404);
+            throw err;
+        }
+        if (s.isDirectory())
+            return c.json({ error: 'is a directory' }, 400);
+        if (s.size > ctx.maxReadBytes)
+            return c.json({ error: 'file too large' }, 413);
+        const buf = await readFile(abs);
+        return c.body(buf, 200, { 'Content-Type': 'application/octet-stream' });
+    });
+}

package/dist/tenant-fs/index.d.ts

@@ -0,0 +1,4 @@
+export * from './paths.js';
+export * from './resolve.js';
+export * from './session-required.js';
+export * from './http.js';

package/dist/tenant-fs/index.js

@@ -0,0 +1,4 @@
+export * from './paths.js';
+export * from './resolve.js';
+export * from './session-required.js';
+export * from './http.js';

package/dist/tenant-fs/paths.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Tenant path helpers — the framework owns the `data/users/<id>/...` layout.
+ *
+ * Two tiers:
+ *   users/<id>/<shardId>/           — shard's private per-user state (internal)
+ *   users/<id>/documents/<shardId>/ — user-facing files (exposed via /api/fs)
+ *
+ * Shards call these helpers server-side. Clients use /api/fs/* to reach
+ * documents/ only — shard state is never served over HTTP.
+ */
+export type TenantRootResolver = (userId: string) => string;
+/**
+ * Back-compat resolver: <base>/<userId>/documents. Equivalent to
+ * documentsRoot() but parameterized by rootBase. Retained for sites that
+ * historically accepted a resolver function.
+ */
+export declare function makeTenantRootResolver(dataDir: string, rootBase: string): TenantRootResolver;
+/** <dataDir>/users/<userId>/documents — the document library root. */
+export declare function documentsRoot(dataDir: string, userId: string, rootBase?: string): string;
+/** <dataDir>/users/<userId>/documents/<shardId> — user docs produced by shard. */
+export declare function shardDocumentsPath(dataDir: string, userId: string, shardId: string, rootBase?: string): string;
+/** <dataDir>/users/<userId>/<shardId> — shard-internal per-user state. */
+export declare function shardStatePath(dataDir: string, userId: string, shardId: string, rootBase?: string): string;

package/dist/tenant-fs/paths.js

@@ -0,0 +1,51 @@
+/**
+ * Tenant path helpers — the framework owns the `data/users/<id>/...` layout.
+ *
+ * Two tiers:
+ *   users/<id>/<shardId>/           — shard's private per-user state (internal)
+ *   users/<id>/documents/<shardId>/ — user-facing files (exposed via /api/fs)
+ *
+ * Shards call these helpers server-side. Clients use /api/fs/* to reach
+ * documents/ only — shard state is never served over HTTP.
+ */
+import { mkdirSync } from 'node:fs';
+import { isAbsolute, join, normalize, resolve } from 'node:path';
+function resolveBase(dataDir, rootBase) {
+    if (rootBase === '')
+        return join(dataDir, 'users');
+    return isAbsolute(rootBase) ? normalize(rootBase) : resolve(dataDir, rootBase);
+}
+/**
+ * Back-compat resolver: <base>/<userId>/documents. Equivalent to
+ * documentsRoot() but parameterized by rootBase. Retained for sites that
+ * historically accepted a resolver function.
+ */
+export function makeTenantRootResolver(dataDir, rootBase) {
+    const base = resolveBase(dataDir, rootBase);
+    return (userId) => {
+        const root = join(base, userId, 'documents');
+        mkdirSync(root, { recursive: true });
+        return root;
+    };
+}
+/** <dataDir>/users/<userId>/documents — the document library root. */
+export function documentsRoot(dataDir, userId, rootBase = '') {
+    const base = resolveBase(dataDir, rootBase);
+    const p = join(base, userId, 'documents');
+    mkdirSync(p, { recursive: true });
+    return p;
+}
+/** <dataDir>/users/<userId>/documents/<shardId> — user docs produced by shard. */
+export function shardDocumentsPath(dataDir, userId, shardId, rootBase = '') {
+    const base = resolveBase(dataDir, rootBase);
+    const p = join(base, userId, 'documents', shardId);
+    mkdirSync(p, { recursive: true });
+    return p;
+}
+/** <dataDir>/users/<userId>/<shardId> — shard-internal per-user state. */
+export function shardStatePath(dataDir, userId, shardId, rootBase = '') {
+    const base = resolveBase(dataDir, rootBase);
+    const p = join(base, userId, shardId);
+    mkdirSync(p, { recursive: true });
+    return p;
+}

package/dist/tenant-fs/resolve.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Containment helper — resolves a relative path under a tenant root and
+ * asserts the real resolved path stays inside the root. Use this for ANY
+ * file I/O that accepts a path from the client.
+ *
+ * - Resolves `rel` against `root`.
+ * - Calls fs.realpath to follow symlinks.
+ * - If the target does not exist yet (e.g. future write ops), realpath
+ *   walks up to the deepest existing ancestor and appends the remainder.
+ * - Throws TenantPathEscapeError if the real path is not root or a descendant.
+ */
+export declare class TenantPathEscapeError extends Error {
+    readonly rel: string;
+    constructor(rel: string);
+}
+export declare function resolveTenantPath(root: string, rel: string): Promise<string>;

package/dist/tenant-fs/resolve.js

@@ -0,0 +1,48 @@
+/**
+ * Containment helper — resolves a relative path under a tenant root and
+ * asserts the real resolved path stays inside the root. Use this for ANY
+ * file I/O that accepts a path from the client.
+ *
+ * - Resolves `rel` against `root`.
+ * - Calls fs.realpath to follow symlinks.
+ * - If the target does not exist yet (e.g. future write ops), realpath
+ *   walks up to the deepest existing ancestor and appends the remainder.
+ * - Throws TenantPathEscapeError if the real path is not root or a descendant.
+ */
+import { realpath } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { resolve, sep, dirname, basename, join } from 'node:path';
+export class TenantPathEscapeError extends Error {
+    rel;
+    constructor(rel) {
+        super(`path escape: ${rel} resolves outside tenant root`);
+        this.rel = rel;
+        this.name = 'TenantPathEscapeError';
+    }
+}
+async function realpathDeepest(p) {
+    // Walk up until we find an existing ancestor, realpath it, then
+    // rejoin the non-existing tail. This lets us validate paths that
+    // do not exist yet (future write ops) without allowing escape via
+    // a non-existent path component.
+    let cursor = p;
+    const tail = [];
+    while (!existsSync(cursor)) {
+        const parent = dirname(cursor);
+        if (parent === cursor)
+            break; // reached filesystem root
+        tail.unshift(basename(cursor));
+        cursor = parent;
+    }
+    const real = await realpath(cursor);
+    return tail.length === 0 ? real : join(real, ...tail);
+}
+export async function resolveTenantPath(root, rel) {
+    const realRoot = await realpath(root);
+    const abs = resolve(realRoot, rel);
+    const real = await realpathDeepest(abs);
+    if (real !== realRoot && !real.startsWith(realRoot + sep)) {
+        throw new TenantPathEscapeError(rel);
+    }
+    return real;
+}

package/dist/tenant-fs/session-required.d.ts

@@ -0,0 +1,11 @@
+import type { MiddlewareHandler } from 'hono';
+import type { SettingsStore } from '../settings.js';
+/**
+ * Requires an authenticated session on the request. Any role passes.
+ * When `auth.required` is false (dev/--no-auth), passes through.
+ *
+ * Contrast with adminOnly: this gate is for tenant-scoped APIs where any
+ * logged-in user can operate — scope is enforced by the handler jailing to
+ * the caller's own tenant root, not by role.
+ */
+export declare function makeSessionRequired(settings: SettingsStore): MiddlewareHandler;

package/dist/tenant-fs/session-required.js

@@ -0,0 +1,19 @@
+/**
+ * Requires an authenticated session on the request. Any role passes.
+ * When `auth.required` is false (dev/--no-auth), passes through.
+ *
+ * Contrast with adminOnly: this gate is for tenant-scoped APIs where any
+ * logged-in user can operate — scope is enforced by the handler jailing to
+ * the caller's own tenant root, not by role.
+ */
+export function makeSessionRequired(settings) {
+    return async (c, next) => {
+        if (!settings.get().auth.required)
+            return next();
+        const session = c.get('session') ?? c.env?.session;
+        if (!session?.userId) {
+            return c.json({ error: 'authentication required' }, 401);
+        }
+        return next();
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sh3-server",
-  "version": "0.7.5",
+  "version": "0.8.2",
   "type": "module",
   "bin": {
     "sh3-server": "dist/cli.js"
@@ -39,7 +39,7 @@
     "@types/node": "^20.0.0",
     "esbuild": "^0.21.5",
     "postject": "^1.0.0-alpha.6",
-    "sh3-core": "0.7.0",
+    "sh3-core": "*",
     "svelte": "^5.0.0",
     "tsx": "^4.0.0",
     "typescript": "^5.6.0",