@feasibleone/blong-gogo 1.14.2 → 1.15.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [1.15.0](https://github.com/feasibleone/blong/compare/blong-gogo-v1.14.3...blong-gogo-v1.15.0) (2026-03-29)
+
+
+### Features
+
+* built-in REST-FS server component for remote filesystem over Gateway ([#108](https://github.com/feasibleone/blong/issues/108)) ([352ef2a](https://github.com/feasibleone/blong/commit/352ef2a86a4da1f29eaf931c6057d018918fedaf))
+
+## [1.14.3](https://github.com/feasibleone/blong/compare/blong-gogo-v1.14.2...blong-gogo-v1.14.3) (2026-03-24)
+
+
+### Bug Fixes
+
+* type generation ([425c3ca](https://github.com/feasibleone/blong/commit/425c3cac5863253c39138a3245be876f0e0a74dd))
+
 ## [1.14.2](https://github.com/feasibleone/blong/compare/blong-gogo-v1.14.1...blong-gogo-v1.14.2) (2026-03-23)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feasibleone/blong-gogo",
-  "version": "1.14.2",
+  "version": "1.15.0",
   "repository": {
     "url": "git+https://github.com/feasibleone/blong.git"
   },

package/src/Gateway.ts

@@ -153,6 +153,7 @@ export default class Gateway extends Internal implements IGateway {
     #routes: RouteOptions[];
     #local: ILocal;
     #errorFields: [string, unknown][] = [];
+    #plugins: {plugin: unknown; options: unknown}[] = [];
 
     public constructor(
         config: IConfig,
@@ -195,6 +196,10 @@ export default class Gateway extends Internal implements IGateway {
         return Object.freeze({...this.#config});
     }
 
+    public registerPlugin(plugin: unknown, options?: unknown): void {
+        this.#plugins.push({plugin, options});
+    }
+
     // https://github.com/openzipkin/b3-propagation
     private _forward(headers: object): object {
         return [
@@ -498,6 +503,8 @@ export default class Gateway extends Internal implements IGateway {
             await this.#server.register(swagger, {
                 version: '',
             });
+            for (const {plugin, options} of this.#plugins)
+                await this.#server.register(plugin, options);
             this.#routes.forEach(route => this.#server.route(route));
         } finally {
             await old?.close();

package/src/RestFs.test.ts

@@ -0,0 +1,341 @@
+/**
+ * Tests for RestFs component — path traversal, CRUD, and edge cases via Fastify injection.
+ */
+
+import assert from 'node:assert';
+import {mkdir, readFile, rm, symlink, writeFile} from 'node:fs/promises';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
+import {after, before, describe, it} from 'node:test';
+
+import fastify, {type FastifyInstance} from 'fastify';
+import fp from 'fastify-plugin';
+import RestFs from './RestFs.ts';
+
+/**
+ * Helper: create an isolated RestFs + Fastify instance for testing.
+ * Returns { server, baseDir, cleanup }.
+ */
+async function setup(options?: {shell?: boolean}): Promise<{
+    server: FastifyInstance;
+    baseDir: string;
+    cleanup: () => Promise<void>;
+}> {
+    const baseDir = join(tmpdir(), `restfs-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    await mkdir(baseDir, {recursive: true});
+
+    // RestFs expects a gateway with registerPlugin — we accumulate the plugin and register it ourselves
+    let capturedPlugin: unknown;
+    let capturedOptions: unknown;
+    const fakeGateway = {
+        registerPlugin(plugin: unknown, opts?: unknown) {
+            capturedPlugin = plugin;
+            capturedOptions = opts;
+        },
+    };
+
+    const restFs = new (RestFs as any)(
+        {enabled: true, baseDir, routePrefix: '/api/fs', maxFileSize: 52428800, auth: false, shell: options?.shell ?? false},
+        {gateway: fakeGateway},
+    );
+    await restFs.init();
+
+    const server = fastify();
+    // Stub auth config so routes don't require it
+    server.addHook('preValidation', (_req, _reply, done) => done());
+    if (capturedPlugin) await server.register(capturedPlugin as any, capturedOptions as any);
+    await server.ready();
+
+    return {
+        server,
+        baseDir,
+        cleanup: async () => {
+            await server.close();
+            await rm(baseDir, {recursive: true, force: true});
+        },
+    };
+}
+
+describe('RestFs', () => {
+    let server: FastifyInstance;
+    let baseDir: string;
+    let cleanup: () => Promise<void>;
+
+    before(async () => {
+        ({server, baseDir, cleanup} = await setup());
+    });
+
+    after(async () => {
+        await cleanup();
+    });
+
+    // ---- CRUD ----
+
+    describe('CRUD operations', () => {
+        it('GET /stat/* — returns 404 for non-existent path', async () => {
+            const res = await server.inject({method: 'GET', url: '/api/fs/stat/does-not-exist'});
+            assert.strictEqual(res.statusCode, 404);
+        });
+
+        it('POST /mkdir/* — creates a directory', async () => {
+            const res = await server.inject({method: 'POST', url: '/api/fs/mkdir/test-dir'});
+            assert.strictEqual(res.statusCode, 200);
+            assert.deepStrictEqual(res.json(), {success: true});
+        });
+
+        it('GET /stat/* — returns metadata for existing directory', async () => {
+            const res = await server.inject({method: 'GET', url: '/api/fs/stat/test-dir'});
+            assert.strictEqual(res.statusCode, 200);
+            const body = res.json();
+            assert.strictEqual(body.type, 'directory');
+            assert.ok(typeof body.mtime === 'number');
+        });
+
+        it('POST /write/* — writes a file', async () => {
+            const content = Buffer.from('hello world');
+            const res = await server.inject({
+                method: 'POST',
+                url: '/api/fs/write/test-dir/file.txt',
+                headers: {'content-type': 'application/octet-stream'},
+                payload: content,
+            });
+            assert.strictEqual(res.statusCode, 200);
+            assert.deepStrictEqual(res.json(), {success: true});
+
+            // Verify the file on disk
+            const written = await readFile(join(baseDir, 'test-dir', 'file.txt'));
+            assert.deepStrictEqual(written, content);
+        });
+
+        it('POST /write/* — returns 415 for non-binary body', async () => {
+            const res = await server.inject({
+                method: 'POST',
+                url: '/api/fs/write/test-dir/bad.txt',
+                headers: {'content-type': 'application/json'},
+                payload: JSON.stringify({text: 'oops'}),
+            });
+            assert.strictEqual(res.statusCode, 415);
+            assert.ok(res.json().error.includes('octet-stream'));
+        });
+
+        it('GET /read/* — reads file contents back', async () => {
+            const res = await server.inject({method: 'GET', url: '/api/fs/read/test-dir/file.txt'});
+            assert.strictEqual(res.statusCode, 200);
+            assert.strictEqual(res.body, 'hello world');
+        });
+
+        it('GET /read/* — returns 404 for non-existent file', async () => {
+            const res = await server.inject({method: 'GET', url: '/api/fs/read/nope.txt'});
+            assert.strictEqual(res.statusCode, 404);
+        });
+
+        it('GET /readdir/* — lists directory entries', async () => {
+            const res = await server.inject({method: 'GET', url: '/api/fs/readdir/test-dir'});
+            assert.strictEqual(res.statusCode, 200);
+            const entries = res.json();
+            assert.ok(Array.isArray(entries));
+            assert.ok(entries.some((e: {name: string}) => e.name === 'file.txt'));
+        });
+
+        it('POST /rename — renames a file', async () => {
+            const res = await server.inject({
+                method: 'POST',
+                url: '/api/fs/rename',
+                payload: {oldPath: 'test-dir/file.txt', newPath: 'test-dir/renamed.txt'},
+            });
+            assert.strictEqual(res.statusCode, 200);
+            assert.deepStrictEqual(res.json(), {success: true});
+        });
+
+        it('POST /copy — copies a file', async () => {
+            const res = await server.inject({
+                method: 'POST',
+                url: '/api/fs/copy',
+                payload: {source: 'test-dir/renamed.txt', destination: 'test-dir/copied.txt'},
+            });
+            assert.strictEqual(res.statusCode, 200);
+            assert.deepStrictEqual(res.json(), {success: true});
+
+            const content = await readFile(join(baseDir, 'test-dir', 'copied.txt'), 'utf-8');
+            assert.strictEqual(content, 'hello world');
+        });
+
+        it('DELETE /delete/* — deletes a file', async () => {
+            const res = await server.inject({method: 'DELETE', url: '/api/fs/delete/test-dir/copied.txt'});
+            assert.strictEqual(res.statusCode, 200);
+            assert.deepStrictEqual(res.json(), {success: true});
+        });
+
+        it('DELETE /delete/* — returns 404 for non-existent path', async () => {
+            const res = await server.inject({method: 'DELETE', url: '/api/fs/delete/nope.txt'});
+            assert.strictEqual(res.statusCode, 404);
+        });
+
+        it('DELETE /delete/* — deletes directory recursively', async () => {
+            const res = await server.inject({
+                method: 'DELETE',
+                url: '/api/fs/delete/test-dir?recursive=true',
+            });
+            assert.strictEqual(res.statusCode, 200);
+        });
+    });
+
+    // ---- Path traversal ----
+
+    describe('Path traversal protection', () => {
+        // Note: URL-level .. traversal is normalized by Fastify before routing,
+        // resulting in 404 (route not matched). This is valid HTTP-level protection.
+        // The handler-level resolveSafePath protection is tested via body-based
+        // endpoints (rename, copy) below, which bypass URL normalization.
+
+        it('rejects .. traversal in URL (Fastify normalizes → 404)', async () => {
+            const res = await server.inject({method: 'GET', url: '/api/fs/stat/../../../etc/passwd'});
+            assert.strictEqual(res.statusCode, 404);
+        });
+
+        it('rejects .. traversal in readdir URL (Fastify normalizes → 404)', async () => {
+            const res = await server.inject({method: 'GET', url: '/api/fs/readdir/../../'});
+            assert.strictEqual(res.statusCode, 404);
+        });
+
+        it('rejects .. traversal in write URL (Fastify normalizes → 404)', async () => {
+            const res = await server.inject({
+                method: 'POST',
+                url: '/api/fs/write/../escape.txt',
+                headers: {'content-type': 'application/octet-stream'},
+                payload: Buffer.from('pwned'),
+            });
+            assert.strictEqual(res.statusCode, 404);
+        });
+
+        it('rejects .. traversal in rename (oldPath) — handler-level', async () => {
+            const res = await server.inject({
+                method: 'POST',
+                url: '/api/fs/rename',
+                payload: {oldPath: '../../etc/passwd', newPath: 'safe.txt'},
+            });
+            assert.strictEqual(res.statusCode, 403);
+        });
+
+        it('rejects .. traversal in rename (newPath) — handler-level', async () => {
+            await writeFile(join(baseDir, 'a.txt'), 'test');
+            const res = await server.inject({
+                method: 'POST',
+                url: '/api/fs/rename',
+                payload: {oldPath: 'a.txt', newPath: '../../escape.txt'},
+            });
+            assert.strictEqual(res.statusCode, 403);
+        });
+
+        it('rejects .. traversal in copy (destination) — handler-level', async () => {
+            await writeFile(join(baseDir, 'b.txt'), 'test');
+            const res = await server.inject({
+                method: 'POST',
+                url: '/api/fs/copy',
+                payload: {source: 'b.txt', destination: '../../escape.txt'},
+            });
+            assert.strictEqual(res.statusCode, 403);
+        });
+    });
+
+    // ---- Symlink escape ----
+
+    describe('Symlink escape protection', () => {
+        it('rejects symlink pointing outside baseDir', async () => {
+            const linkPath = join(baseDir, 'evil-link');
+            try {
+                await symlink('/tmp', linkPath);
+            } catch {
+                // symlink creation may fail on some CI — skip
+                return;
+            }
+            const res = await server.inject({method: 'GET', url: '/api/fs/stat/evil-link'});
+            assert.strictEqual(res.statusCode, 403);
+        });
+
+        it('rejects write through symlinked parent directory', async () => {
+            const linkPath = join(baseDir, 'escape-dir');
+            try {
+                await symlink('/tmp', linkPath);
+            } catch {
+                return;
+            }
+            const res = await server.inject({
+                method: 'POST',
+                url: '/api/fs/write/escape-dir/file.txt',
+                headers: {'content-type': 'application/octet-stream'},
+                payload: Buffer.from('pwned'),
+            });
+            assert.strictEqual(res.statusCode, 403);
+        });
+    });
+});
+
+describe('RestFs disabled', () => {
+    it('does not register plugin when enabled is false', async () => {
+        let registered = false;
+        const fakeGateway = {
+            registerPlugin() {
+                registered = true;
+            },
+        };
+        const restFs = new (RestFs as any)(
+            {enabled: false, baseDir: '/tmp', routePrefix: '/api/fs', maxFileSize: 1024, auth: false, shell: false},
+            {gateway: fakeGateway},
+        );
+        await restFs.init();
+        assert.strictEqual(registered, false, 'Plugin should not be registered when disabled');
+    });
+
+    it('does not register plugin when gateway is missing', async () => {
+        const restFs = new (RestFs as any)(
+            {enabled: true, baseDir: '/tmp', routePrefix: '/api/fs', maxFileSize: 1024, auth: false, shell: false},
+            {},
+        );
+        // Should not throw
+        await restFs.init();
+    });
+});
+
+describe('RestFs shell endpoint', () => {
+    let server: FastifyInstance;
+    let baseDir: string;
+    let cleanup: () => Promise<void>;
+
+    before(async () => {
+        ({server, baseDir, cleanup} = await setup({shell: true}));
+    });
+
+    after(async () => {
+        await cleanup();
+    });
+
+    it('POST /shell — executes a command and streams output', async () => {
+        const res = await server.inject({
+            method: 'POST',
+            url: '/api/fs/shell',
+            payload: {command: 'echo hello'},
+        });
+        // Shell uses raw streaming; inject returns the raw response
+        assert.strictEqual(res.statusCode, 200);
+        assert.ok(res.body.includes('hello'));
+    });
+
+    it('POST /shell — returns 400 when command is missing', async () => {
+        const res = await server.inject({
+            method: 'POST',
+            url: '/api/fs/shell',
+            payload: {command: ''},
+        });
+        assert.strictEqual(res.statusCode, 400);
+    });
+
+    it('POST /shell — validates cwd within baseDir', async () => {
+        const res = await server.inject({
+            method: 'POST',
+            url: '/api/fs/shell',
+            payload: {command: 'pwd', cwd: '../../'},
+        });
+        assert.strictEqual(res.statusCode, 400);
+    });
+});

package/src/RestFs.ts

@@ -0,0 +1,386 @@
+import {Internal, type ILog} from '@feasibleone/blong/types';
+import type {FastifyInstance, FastifyReply, FastifyRequest} from 'fastify';
+import fp from 'fastify-plugin';
+import {spawn} from 'node:child_process';
+import {
+    copyFile,
+    cp,
+    mkdir,
+    readdir,
+    readFile,
+    realpath,
+    rename,
+    rm,
+    stat,
+    unlink,
+    writeFile,
+} from 'node:fs/promises';
+import {dirname, isAbsolute, join, relative, resolve, sep} from 'node:path';
+import {pipeline} from 'node:stream/promises';
+
+interface IConfig {
+    enabled: boolean;
+    baseDir: string;
+    routePrefix: string;
+    maxFileSize: number;
+    auth: false | 'jwt';
+    shell: boolean;
+}
+
+interface IGatewayWithPlugins {
+    registerPlugin(plugin: unknown, options?: unknown): void;
+}
+
+export default class RestFs extends Internal {
+    #config: IConfig = {
+        enabled: false,
+        baseDir: process.cwd(),
+        routePrefix: '/api/fs',
+        maxFileSize: 52428800, // 50MB
+        auth: false,
+        shell: false,
+    };
+
+    #gateway: IGatewayWithPlugins;
+
+    public constructor(
+        config: IConfig,
+        {log, gateway}: {log?: ILog; gateway?: IGatewayWithPlugins},
+    ) {
+        super({log});
+        this.merge(this.#config, config);
+        this.#gateway = gateway;
+    }
+
+    public async init(): Promise<void> {
+        if (!this.#config.enabled || !this.#gateway) return;
+
+        const config = this.#config;
+        const baseDir = resolve(config.baseDir);
+
+        await mkdir(baseDir, {recursive: true});
+
+        const isWithinBase = (candidate: string): boolean => {
+            if (candidate === baseDir) return true;
+            const rel = relative(baseDir, candidate);
+            return !rel.startsWith('..') && !isAbsolute(rel) && !rel.startsWith('..' + sep);
+        };
+
+        const resolveSafePath = async (requestPath: string): Promise<string> => {
+            const joined = join(baseDir, requestPath || '/');
+            const resolved = resolve(joined);
+            if (!isWithinBase(resolved)) {
+                const error = new Error('Access denied: path outside base directory');
+                (error as NodeJS.ErrnoException).code = 'EACCES';
+                throw error;
+            }
+            // Walk up to the nearest existing ancestor and realpath-check it
+            // to prevent symlink-escape attacks on non-existent paths
+            let check = resolved;
+            let real: string | undefined;
+            while (check !== baseDir) {
+                try {
+                    real = await realpath(check);
+                    break;
+                } catch (err) {
+                    if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+                        check = dirname(check);
+                        continue;
+                    }
+                    throw err;
+                }
+            }
+            if (real && !isWithinBase(real)) {
+                const error = new Error('Access denied: path outside base directory');
+                (error as NodeJS.ErrnoException).code = 'EACCES';
+                throw error;
+            }
+            // If the full path exists, return the realpath; otherwise the resolved path
+            if (real && check === resolved) return real;
+            return resolved;
+        };
+
+        const fsError = (
+            reply: FastifyReply,
+            err: unknown,
+        ): FastifyReply => {
+            const error = err as NodeJS.ErrnoException;
+            switch (error.code) {
+                case 'ENOENT':
+                    return reply.code(404).send({error: 'Not found'});
+                case 'EACCES':
+                    return reply.code(403).send({error: error.message || 'Access denied'});
+                case 'ENOTEMPTY':
+                    return reply
+                        .code(400)
+                        .send({error: 'Directory not empty (use recursive=true)'});
+                default:
+                    return reply.code(500).send({error: error.message || 'Internal server error'});
+            }
+        };
+
+        const authConfig = config.auth;
+
+        const plugin = fp(
+            async (server: FastifyInstance) => {
+                const prefix = config.routePrefix;
+
+                // Add raw body parser for octet-stream content
+                server.addContentTypeParser(
+                    'application/octet-stream',
+                    {parseAs: 'buffer', bodyLimit: config.maxFileSize},
+                    (_req, body, done) => {
+                        done(null, body);
+                    },
+                );
+
+                // GET /stat/* — file/directory metadata
+                server.route({
+                    method: 'GET',
+                    url: `${prefix}/stat/*`,
+                    config: {auth: authConfig},
+                    handler: async (
+                        request: FastifyRequest<{Params: {'*': string}}>,
+                        reply,
+                    ) => {
+                        try {
+                            const fullPath = await resolveSafePath(request.params['*']);
+                            const stats = await stat(fullPath);
+                            return {
+                                type: stats.isDirectory() ? 'directory' : 'file',
+                                ctime: stats.ctimeMs,
+                                mtime: stats.mtimeMs,
+                                size: stats.size,
+                            };
+                        } catch (err) {
+                            return fsError(reply, err);
+                        }
+                    },
+                });
+
+                // GET /readdir/* — directory listing
+                server.route({
+                    method: 'GET',
+                    url: `${prefix}/readdir/*`,
+                    config: {auth: authConfig},
+                    handler: async (
+                        request: FastifyRequest<{Params: {'*': string}}>,
+                        reply,
+                    ) => {
+                        try {
+                            const fullPath = await resolveSafePath(request.params['*']);
+                            const entries = await readdir(fullPath, {withFileTypes: true});
+                            return entries.map(entry => ({
+                                name: entry.name,
+                                type: entry.isDirectory() ? 'directory' : 'file',
+                            }));
+                        } catch (err) {
+                            return fsError(reply, err);
+                        }
+                    },
+                });
+
+                // POST /mkdir/* — create directory
+                server.route({
+                    method: 'POST',
+                    url: `${prefix}/mkdir/*`,
+                    config: {auth: authConfig},
+                    handler: async (
+                        request: FastifyRequest<{Params: {'*': string}}>,
+                        reply,
+                    ) => {
+                        try {
+                            const fullPath = await resolveSafePath(request.params['*']);
+                            await mkdir(fullPath, {recursive: true});
+                            return {success: true};
+                        } catch (err) {
+                            return fsError(reply, err);
+                        }
+                    },
+                });
+
+                // GET /read/* — read file contents
+                server.route({
+                    method: 'GET',
+                    url: `${prefix}/read/*`,
+                    config: {auth: authConfig},
+                    handler: async (
+                        request: FastifyRequest<{Params: {'*': string}}>,
+                        reply,
+                    ) => {
+                        try {
+                            const fullPath = await resolveSafePath(request.params['*']);
+                            const content = await readFile(fullPath);
+                            return reply.type('application/octet-stream').send(content);
+                        } catch (err) {
+                            return fsError(reply, err);
+                        }
+                    },
+                });
+
+                // POST /write/* — write file contents
+                server.route({
+                    method: 'POST',
+                    url: `${prefix}/write/*`,
+                    config: {auth: authConfig},
+                    handler: async (
+                        request: FastifyRequest<{Params: {'*': string}}>,
+                        reply,
+                    ) => {
+                        try {
+                            const body = request.body;
+                            if (!Buffer.isBuffer(body)) {
+                                return reply.code(415).send({
+                                    error: 'Unsupported media type: expected application/octet-stream',
+                                });
+                            }
+                            const fullPath = await resolveSafePath(request.params['*']);
+                            await mkdir(dirname(fullPath), {recursive: true});
+                            await writeFile(fullPath, body);
+                            return {success: true};
+                        } catch (err) {
+                            return fsError(reply, err);
+                        }
+                    },
+                });
+
+                // DELETE /delete/* — delete file or directory
+                server.route({
+                    method: 'DELETE',
+                    url: `${prefix}/delete/*`,
+                    config: {auth: authConfig},
+                    handler: async (
+                        request: FastifyRequest<{
+                            Params: {'*': string};
+                            Querystring: {recursive?: string};
+                        }>,
+                        reply,
+                    ) => {
+                        try {
+                            const fullPath = await resolveSafePath(request.params['*']);
+                            const recursive = request.query.recursive === 'true';
+                            const stats = await stat(fullPath);
+                            if (stats.isDirectory()) {
+                                await rm(fullPath, {recursive});
+                            } else {
+                                await unlink(fullPath);
+                            }
+                            return {success: true};
+                        } catch (err) {
+                            return fsError(reply, err);
+                        }
+                    },
+                });
+
+                // POST /rename — rename/move
+                server.route({
+                    method: 'POST',
+                    url: `${prefix}/rename`,
+                    config: {auth: authConfig},
+                    handler: async (
+                        request: FastifyRequest<{Body: {oldPath: string; newPath: string}}>,
+                        reply,
+                    ) => {
+                        try {
+                            const {oldPath, newPath} = request.body;
+                            const oldFullPath = await resolveSafePath(oldPath);
+                            const newFullPath = await resolveSafePath(newPath);
+                            await rename(oldFullPath, newFullPath);
+                            return {success: true};
+                        } catch (err) {
+                            return fsError(reply, err);
+                        }
+                    },
+                });
+
+                // POST /copy — copy file or directory
+                server.route({
+                    method: 'POST',
+                    url: `${prefix}/copy`,
+                    config: {auth: authConfig},
+                    handler: async (
+                        request: FastifyRequest<{
+                            Body: {source: string; destination: string};
+                        }>,
+                        reply,
+                    ) => {
+                        try {
+                            const {source, destination} = request.body;
+                            const sourceFullPath = await resolveSafePath(source);
+                            const destFullPath = await resolveSafePath(destination);
+                            const stats = await stat(sourceFullPath);
+                            if (stats.isDirectory()) {
+                                await cp(sourceFullPath, destFullPath, {recursive: true});
+                            } else {
+                                await copyFile(sourceFullPath, destFullPath);
+                            }
+                            return {success: true};
+                        } catch (err) {
+                            return fsError(reply, err);
+                        }
+                    },
+                });
+
+                // POST /shell — execute shell command with streaming output
+                if (config.shell) {
+                    server.route({
+                        method: 'POST',
+                        url: `${prefix}/shell`,
+                        // Shell endpoint always requires auth when enabled
+                        config: {auth: authConfig || 'jwt'},
+                        handler: async (
+                            request: FastifyRequest<{Body: {command: string; cwd?: string}}>,
+                            reply,
+                        ) => {
+                            const {command, cwd} = request.body;
+                            if (!command) {
+                                return reply.code(400).send({error: 'Command is required'});
+                            }
+
+                            let workingDir: string;
+                            try {
+                                workingDir = cwd
+                                    ? await resolveSafePath(cwd)
+                                    : baseDir;
+                            } catch {
+                                return reply
+                                    .code(400)
+                                    .send({error: 'Invalid working directory'});
+                            }
+
+                            reply.raw.writeHead(200, {
+                                'content-type': 'text/plain; charset=utf-8',
+                                'transfer-encoding': 'chunked',
+                                'cache-control': 'no-cache',
+                                'x-content-type-options': 'nosniff',
+                            });
+
+                            const child = spawn(command, [], {
+                                cwd: workingDir,
+                                shell: true,
+                                env: process.env,
+                            });
+
+                            request.raw.on('close', () => child.kill());
+
+                            try {
+                                await Promise.all([
+                                    pipeline(child.stdout, reply.raw, {end: false}),
+                                    pipeline(child.stderr, reply.raw, {end: false}),
+                                    new Promise(resolve => child.on('close', resolve)),
+                                ]);
+                            } catch {
+                                // Streaming error — client may have disconnected
+                            } finally {
+                                reply.raw.end();
+                            }
+                        },
+                    });
+                }
+            },
+            {name: 'rest-fs'},
+        );
+
+        this.#gateway.registerPlugin(plugin);
+    }
+}

package/src/Watch.ts

@@ -151,11 +151,11 @@ export default class Watch extends Internal implements IWatch {
             });
 
             declare module '@feasibleone/blong' {
-                interface IRemoteHandler {
+                interface ISchema {
                     ${names
                         .map(
                             name =>
-                                `${name}<T=ReturnType<${name}>>(params: Parameters<${name}>[0], $meta: IMeta): T;`,
+                                `${name}(params: Parameters<${name}>[0], $meta: IMeta): ReturnType<${name}>;`,
                         )
                         .join('\n')}
                 }

package/src/load.ts

@@ -265,6 +265,7 @@ export default async function loadRealm<T extends TSchema>(
             local: {},
             rpcServer: {},
             gateway: {},
+            restFs: {},
         });
         items = [
             function log() {
@@ -299,6 +300,9 @@ export default async function loadRealm<T extends TSchema>(
                     function gateway() {
                         return import('./Gateway.ts');
                     },
+                    function restFs() {
+                        return import('./RestFs.ts');
+                    },
                     function registry() {
                         return import('./Registry.ts');
                     },