ai image video fs output (#3079)

* Add puter_output_path

* Fix error reporting in puterjs. Add precheck for puterOutputPath

* add tests

* add tests

* frontend puterjs tests

Author: ProgrammerIn-wonderland

src/backend/drivers/ai-image/ImageGenerationDriver.test.ts

@@ -410,6 +410,210 @@ describe('ImageGenerationDriver.generate audit log', () => {
     });
 });
 
+// ── puter_output_path ─────────────────────────────────────────────
+
+describe('ImageGenerationDriver.generate puter_output_path', () => {
+    const TEST_ACTOR: import('../../core/actor.js').Actor = {
+        user: { uuid: 'a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d', id: 42, username: 'testuser' },
+    };
+
+    const withTestUser = <T>(fn: () => T | Promise<T>): Promise<T> =>
+        Promise.resolve(runWithContext({ actor: TEST_ACTOR }, fn));
+
+    it('throws 400 when puter_output_path resolves to root', async () => {
+        await expect(
+            withTestUser(() =>
+                driver.generate({
+                    model: 'dall-e-2',
+                    prompt: 'hi',
+                    puter_output_path: '/',
+                } as never),
+            ),
+        ).rejects.toMatchObject({ statusCode: 400 });
+
+        expect(openaiImagesGenerateMock).not.toHaveBeenCalled();
+    });
+
+    it('throws 400 when puter_output_path parent is root (e.g. /image.png)', async () => {
+        await expect(
+            withTestUser(() =>
+                driver.generate({
+                    model: 'dall-e-2',
+                    prompt: 'hi',
+                    puter_output_path: '/image.png',
+                } as never),
+            ),
+        ).rejects.toMatchObject({ statusCode: 400 });
+
+        expect(openaiImagesGenerateMock).not.toHaveBeenCalled();
+    });
+
+    it('throws 403 when ACL denies write access to the destination', async () => {
+        const aclCheckSpy = vi.spyOn(server.services.acl, 'check');
+        aclCheckSpy.mockResolvedValueOnce(false);
+
+        await expect(
+            withTestUser(() =>
+                driver.generate({
+                    model: 'dall-e-2',
+                    prompt: 'hi',
+                    puter_output_path: '/testuser/somedir/image.png',
+                } as never),
+            ),
+        ).rejects.toMatchObject({ statusCode: 403 });
+
+        expect(openaiImagesGenerateMock).not.toHaveBeenCalled();
+    });
+
+    it('ACL check runs BEFORE provider.generate so credits are not wasted on a denied path', async () => {
+        const callOrder: string[] = [];
+        const aclCheckSpy = vi.spyOn(server.services.acl, 'check');
+        aclCheckSpy.mockImplementation(async () => {
+            callOrder.push('acl');
+            return false;
+        });
+        openaiImagesGenerateMock.mockImplementation(async () => {
+            callOrder.push('provider');
+            return { data: [{ url: 'https://oai/img.png' }] };
+        });
+
+        await expect(
+            withTestUser(() =>
+                driver.generate({
+                    model: 'dall-e-2',
+                    prompt: 'hi',
+                    puter_output_path: '/testuser/dir/img.png',
+                } as never),
+            ),
+        ).rejects.toMatchObject({ statusCode: 403 });
+
+        expect(callOrder).toEqual(['acl']);
+    });
+
+    it('resolves ~ in puter_output_path to /<username>/', async () => {
+        const aclCheckSpy = vi.spyOn(server.services.acl, 'check');
+        aclCheckSpy.mockResolvedValueOnce(true);
+
+        const fsWriteSpy = vi.spyOn(server.services.fs, 'write');
+        fsWriteSpy.mockResolvedValueOnce(undefined as never);
+
+        openaiImagesGenerateMock.mockResolvedValueOnce({
+            data: [{ url: 'https://oai/img.png' }],
+        });
+        fetchSpy.mockResolvedValueOnce(
+            new Response(Buffer.from('fake-png'), {
+                status: 200,
+                headers: { 'content-type': 'image/png' },
+            }),
+        );
+
+        await withTestUser(() =>
+            driver.generate({
+                model: 'dall-e-2',
+                prompt: 'hi',
+                puter_output_path: '~/images/out.png',
+            } as never),
+        );
+
+        expect(fsWriteSpy).toHaveBeenCalledTimes(1);
+        const [, writeArg] = fsWriteSpy.mock.calls[0]!;
+        expect(
+            (writeArg as { fileMetadata: { path: string } }).fileMetadata.path,
+        ).toBe('/testuser/images/out.png');
+    });
+
+    it('writes the generated image to FS and still returns the result URL', async () => {
+        const aclCheckSpy = vi.spyOn(server.services.acl, 'check');
+        aclCheckSpy.mockResolvedValueOnce(true);
+
+        const fsWriteSpy = vi.spyOn(server.services.fs, 'write');
+        fsWriteSpy.mockResolvedValueOnce(undefined as never);
+
+        openaiImagesGenerateMock.mockResolvedValueOnce({
+            data: [{ url: 'https://oai/img.png' }],
+        });
+        fetchSpy.mockResolvedValueOnce(
+            new Response(Buffer.from('fake-png'), {
+                status: 200,
+                headers: { 'content-type': 'image/png' },
+            }),
+        );
+
+        const result = await withTestUser(() =>
+            driver.generate({
+                model: 'dall-e-2',
+                prompt: 'hi',
+                puter_output_path: '/testuser/photos/out.png',
+            } as never),
+        );
+
+        expect(result).toBe('https://oai/img.png');
+        expect(fsWriteSpy).toHaveBeenCalledTimes(1);
+        const [userId, writeArg] = fsWriteSpy.mock.calls[0]!;
+        expect(userId).toBe(42);
+        const meta = (
+            writeArg as {
+                fileMetadata: {
+                    path: string;
+                    contentType: string;
+                    overwrite: boolean;
+                };
+            }
+        ).fileMetadata;
+        expect(meta.path).toBe('/testuser/photos/out.png');
+        expect(meta.contentType).toBe('image/png');
+        expect(meta.overwrite).toBe(true);
+    });
+
+    it('does not forward puter_output_path to the upstream provider call', async () => {
+        const aclCheckSpy = vi.spyOn(server.services.acl, 'check');
+        aclCheckSpy.mockResolvedValueOnce(true);
+
+        const fsWriteSpy = vi.spyOn(server.services.fs, 'write');
+        fsWriteSpy.mockResolvedValueOnce(undefined as never);
+
+        openaiImagesGenerateMock.mockResolvedValueOnce({
+            data: [{ url: 'https://oai/img.png' }],
+        });
+        fetchSpy.mockResolvedValueOnce(
+            new Response(Buffer.from('fake-png'), {
+                status: 200,
+                headers: { 'content-type': 'image/png' },
+            }),
+        );
+
+        await withTestUser(() =>
+            driver.generate({
+                model: 'dall-e-2',
+                prompt: 'hi',
+                puter_output_path: '/testuser/dir/img.png',
+            } as never),
+        );
+
+        const sent = openaiImagesGenerateMock.mock.calls[0]![0];
+        expect(sent.puter_output_path).toBeUndefined();
+    });
+
+    it('throws 400 when actor has no user ID but puter_output_path is set', async () => {
+        const noIdActor: import('../../core/actor.js').Actor = {
+            user: { uuid: 'f0e1d2c3-b4a5-4968-8777-0a1b2c3d4e5f', username: 'noone' },
+        };
+        await expect(
+            Promise.resolve(
+                runWithContext({ actor: noIdActor }, () =>
+                    driver.generate({
+                        model: 'dall-e-2',
+                        prompt: 'hi',
+                        puter_output_path: '/noone/dir/img.png',
+                    } as never),
+                ),
+            ),
+        ).rejects.toMatchObject({ statusCode: 400 });
+
+        expect(openaiImagesGenerateMock).not.toHaveBeenCalled();
+    });
+});
+
 // Avoid coupling the 'unused' XAI export to lint. The catalog reference
 // is also used implicitly by the routing tests above.
 void XAI_IMAGE_GENERATION_MODELS;

src/backend/drivers/ai-image/ImageGenerationDriver.ts

@@ -18,8 +18,11 @@
  */
 
 import crypto from 'node:crypto';
+import { posix as pathPosix } from 'node:path';
+import { Readable } from 'node:stream';
 import { Context } from '../../core/context.js';
 import { HttpError } from '../../core/http/HttpError.js';
+import type { Actor } from '../../core/actor.js';
 import { PuterDriver } from '../types.js';
 import { AI_CONCURRENT, AI_RATE_LIMIT } from '../util/aiLimits.js';
 import { CloudflareImageProvider } from './providers/cloudflare/CloudflareImageProvider.js';
@@ -114,12 +117,34 @@ export class ImageGenerationDriver extends PuterDriver {
     }
 
     async generate(args: IGenerateParams): Promise<string> {
-        const actor = Context.get('actor');
+        const actor = Context.get('actor') as Actor | undefined;
         if (!actor)
             throw new HttpError(401, 'Authentication required', {
                 legacyCode: 'unauthorized',
             });
 
+        const puterOutputPath = args.puter_output_path;
+        delete args.puter_output_path;
+
+        // Validate the output path early — before spending credits.
+        let resolvedOutputPath: string | undefined;
+        if (puterOutputPath) {
+            const username = actor.user?.username;
+            const userId = actor.user?.id;
+            if (!userId || !username) {
+                throw new HttpError(
+                    400,
+                    'User ID required for puter_output_path',
+                    { legacyCode: 'bad_request' },
+                );
+            }
+            resolvedOutputPath = this.#resolveOutputPath(
+                puterOutputPath,
+                username,
+            );
+            await this.#assertWriteAccess(actor, resolvedOutputPath);
+        }
+
         let modelId = args.model?.trim().toLowerCase();
         let intendedProvider =
             args.provider ?? (Context.get('driverName') as string | undefined);
@@ -172,11 +197,17 @@ export class ImageGenerationDriver extends PuterDriver {
             {},
         );
 
-        return provider.generate({
+        const result = await provider.generate({
             ...args,
             model: model.id,
             provider: model.provider,
         });
+
+        if (resolvedOutputPath) {
+            await this.#saveToFS(actor, result, resolvedOutputPath);
+        }
+
+        return result;
     }
 
     #normalizeRatio(parameters: IGenerateParams) {
@@ -340,6 +371,106 @@ export class ImageGenerationDriver extends PuterDriver {
         }
     }
 
+    async #saveToFS(
+        actor: Actor,
+        result: string,
+        resolvedPath: string,
+    ): Promise<void> {
+        const userId = actor.user!.id!;
+
+        let buffer: Buffer;
+        let contentType: string;
+
+        if (result.startsWith('data:')) {
+            const commaIdx = result.indexOf(',');
+            const header = result.substring(0, commaIdx);
+            contentType =
+                header.match(/data:(.*?);/)?.[1] ?? 'application/octet-stream';
+            buffer = Buffer.from(result.substring(commaIdx + 1), 'base64');
+        } else {
+            const response = await fetch(result);
+            if (!response.ok) {
+                throw new HttpError(
+                    502,
+                    `Failed to fetch generated image for FS write: ${response.status}`,
+                    { legacyCode: 'internal_error' },
+                );
+            }
+            contentType =
+                response.headers.get('content-type') ??
+                'application/octet-stream';
+            buffer = Buffer.from(await response.arrayBuffer());
+        }
+
+        await this.services.fs.write(userId, {
+            fileMetadata: {
+                path: resolvedPath,
+                size: buffer.length,
+                contentType,
+                overwrite: true,
+                createMissingParents: true,
+            },
+            fileContent: Readable.from(buffer),
+        });
+    }
+
+    #resolveOutputPath(outputPath: string, username: string): string {
+        let resolved = outputPath.trim();
+        if (resolved === '~' || resolved.startsWith('~/')) {
+            resolved = `/${username}${resolved.slice(1)}`;
+        }
+        resolved = pathPosix.normalize(resolved);
+        if (!resolved.startsWith('/')) {
+            resolved = `/${resolved}`;
+        }
+        if (resolved.length > 1 && resolved.endsWith('/')) {
+            resolved = resolved.slice(0, -1);
+        }
+        return resolved;
+    }
+
+    async #assertWriteAccess(
+        actor: Actor,
+        resolvedPath: string,
+    ): Promise<void> {
+        if (resolvedPath === '/') {
+            throw new HttpError(400, 'Cannot write to root path', {
+                legacyCode: 'cannot_write_to_root',
+            });
+        }
+        const parentPath = pathPosix.dirname(resolvedPath);
+        if (parentPath === '/') {
+            throw new HttpError(400, 'Cannot write to root path', {
+                legacyCode: 'cannot_write_to_root',
+            });
+        }
+
+        const pathToCheck = parentPath;
+        const fsService = this.services.fs;
+        let ancestorsCache: Promise<
+            Array<{ uid: string; path: string }>
+        > | null = null;
+        const canWrite = await this.services.acl.check(
+            actor,
+            {
+                path: pathToCheck,
+                resolveAncestors() {
+                    if (!ancestorsCache) {
+                        ancestorsCache =
+                            fsService.getAncestorChain(pathToCheck);
+                    }
+                    return ancestorsCache;
+                },
+            },
+            'write',
+        );
+        if (!canWrite) {
+            throw new HttpError(403, 'Write access denied for destination', {
+                legacyCode: 'access_denied',
+            });
+        }
+    }
+
     #resolveModel(modelId: string, provider?: string): IImageModel | null {
         const models = this.#modelIdMap[modelId];
         if (!models || models.length === 0) return null;

src/backend/drivers/ai-image/types.ts

@@ -63,6 +63,7 @@ export interface IGenerateParams {
     input_image?: string;
     input_image_mime_type?: string;
     input_images?: string[];
+    puter_output_path?: string;
     [key: string]: unknown;
 }