@critical-path/core 0.30.0 → 0.31.0

package/src/storage/s3.ts

@@ -5,150 +5,147 @@ import type {
   PresignedUrlOptions,
   PresignedUploadResult
 } from '../types/index.js';
-import { normalizeUploadData } from './file-storage.js';
+import { buildStorageKey, contentDispositionFor, normalizeUploadData } from './file-storage.js';
 
-export interface S3ClientInterface {
-  send?(command: any): Promise<any>;
-  putObject?(params: any): Promise<any>;
-  deleteObject?(params: any): Promise<any>;
-  getSignedUrlPromise?(operation: string, params: any): Promise<string>;
+/** The subset of the AWS SDK v3 `S3Client` the adapter uses. */
+export interface S3ClientLike {
+  send(command: unknown): Promise<unknown>;
+}
+
+type CommandClass = new (input: Record<string, unknown>) => unknown;
+
+/**
+ * Command classes from `@aws-sdk/client-s3`, passed in so `@critical-path/core` has no AWS
+ * dependency: `{ PutObjectCommand, DeleteObjectCommand, GetObjectCommand }`.
+ */
+export interface S3Commands {
+  PutObjectCommand: CommandClass;
+  DeleteObjectCommand: CommandClass;
+  /** Needed for signed download URLs (private buckets). */
+  GetObjectCommand?: CommandClass;
 }
 
 export interface S3StorageConfig {
   bucket: string;
   region?: string;
+  /** Custom endpoint for S3-compatible services (MinIO, R2, LocalStack). */
   endpoint?: string;
-  accessKeyId?: string;
-  secretAccessKey?: string;
-  sessionToken?: string;
+  /** Base URL for public object links (e.g. a CDN). */
   publicUrlBase?: string;
   forcePathStyle?: boolean;
-  s3Client?: S3ClientInterface;
+  /** An AWS SDK v3 `S3Client` (or compatible). Required for uploads and deletes. */
+  client?: S3ClientLike;
+  commands?: S3Commands;
+  /**
+   * Signs a command into a URL, typically
+   * `(command, { expiresIn }) => getSignedUrl(client, command, { expiresIn })` from
+   * `@aws-sdk/s3-request-presigner`. Required for presigned uploads and signed downloads.
+   */
+  presign?: (command: unknown, options: { expiresIn: number }) => Promise<string>;
+  /**
+   * Serve downloads through signed URLs instead of public object URLs (for private buckets).
+   * Requires `presign` and `commands.GetObjectCommand`. Default `false`.
+   */
+  signedDownloads?: boolean;
+  /** Lifetime of signed download URLs in seconds. Default 3600. */
+  downloadUrlExpiresIn?: number;
 }
 
+/**
+ * Stores attachments in Amazon S3 (or an S3-compatible service) using the AWS SDK v3 client
+ * you provide. Errors from S3 propagate; nothing is reported as stored unless S3 accepted it.
+ */
 export class S3StorageAdapter implements FileStorageAdapter {
-  private bucket: string;
-  private region: string;
-  private endpoint: string;
-  private accessKeyId?: string;
-  private secretAccessKey?: string;
-  private sessionToken?: string;
-  private publicUrlBase?: string;
-  private forcePathStyle: boolean;
-  private s3Client?: S3ClientInterface;
+  private readonly bucket: string;
+  private readonly endpoint: string;
+  private readonly publicUrlBase?: string;
+  private readonly forcePathStyle: boolean;
+  private readonly config: S3StorageConfig;
 
   constructor(config: S3StorageConfig) {
     if (!config.bucket) {
       throw new Error('S3StorageAdapter requires a "bucket" name in its config.');
     }
+    if (config.client && !config.commands) {
+      throw new Error('S3StorageAdapter needs "commands" ({ PutObjectCommand, DeleteObjectCommand }) from @aws-sdk/client-s3 when a client is given.');
+    }
+    if (config.signedDownloads && (!config.presign || !config.commands?.GetObjectCommand)) {
+      throw new Error('S3StorageAdapter signedDownloads requires "presign" and "commands.GetObjectCommand".');
+    }
+    this.config = config;
     this.bucket = config.bucket;
-    this.region = config.region || 'us-east-1';
-    this.endpoint = (config.endpoint || `https://s3.${this.region}.amazonaws.com`).replace(/\/+$/, '');
-    this.accessKeyId = config.accessKeyId;
-    this.secretAccessKey = config.secretAccessKey;
-    this.sessionToken = config.sessionToken;
+    const region = config.region || 'us-east-1';
+    this.endpoint = (config.endpoint || `https://s3.${region}.amazonaws.com`).replace(/\/+$/, '');
     this.publicUrlBase = config.publicUrlBase?.replace(/\/+$/, '');
-    this.forcePathStyle = config.forcePathStyle ?? (this.endpoint.includes('localhost') || this.endpoint.includes('127.0.0.1'));
-    this.s3Client = config.s3Client;
+    this.forcePathStyle =
+      config.forcePathStyle ?? (this.endpoint.includes('localhost') || this.endpoint.includes('127.0.0.1'));
   }
 
-  private getObjectUrl(storageKey: string): string {
-    if (this.publicUrlBase) {
-      return `${this.publicUrlBase}/${encodeURIComponent(storageKey).replace(/%2F/g, '/')}`;
-    }
-    if (this.forcePathStyle) {
-      return `${this.endpoint}/${this.bucket}/${encodeURIComponent(storageKey).replace(/%2F/g, '/')}`;
+  private requireClient(operation: string): { client: S3ClientLike; commands: S3Commands } {
+    if (!this.config.client || !this.config.commands) {
+      throw new Error(`S3StorageAdapter cannot ${operation}: configure "client" and "commands".`);
     }
-    const hostWithBucket = this.endpoint.replace('://', `://${this.bucket}.`);
-    return `${hostWithBucket}/${encodeURIComponent(storageKey).replace(/%2F/g, '/')}`;
+    return { client: this.config.client, commands: this.config.commands };
   }
 
-  async upload(input: UploadFileInput): Promise<UploadFileResult> {
-    const prefix = input.pathPrefix ? `${input.pathPrefix.replace(/\/+$/, '')}/` : '';
-    const randomId = Math.random().toString(36).substring(2, 9);
-    const sanitizedFilename = input.filename.replace(/[^a-zA-Z0-9._-]/g, '_');
-    const storageKey = `${prefix}${Date.now()}_${randomId}_${sanitizedFilename}`;
+  private getObjectUrl(storageKey: string): string {
+    const path = encodeURIComponent(storageKey).replace(/%2F/g, '/');
+    if (this.publicUrlBase) return `${this.publicUrlBase}/${path}`;
+    if (this.forcePathStyle) return `${this.endpoint}/${this.bucket}/${path}`;
+    return `${this.endpoint.replace('://', `://${this.bucket}.`)}/${path}`;
+  }
 
-    const bodyData = normalizeUploadData(input.data, input.encoding, input.mimeType);
+  async upload(input: UploadFileInput): Promise<UploadFileResult> {
+    const { client, commands } = this.requireClient('upload');
+    const storageKey = buildStorageKey(input.pathPrefix, input.filename);
+    const body = normalizeUploadData(input.data, input.encoding, input.mimeType);
     const mimeType = input.mimeType || 'application/octet-stream';
-    const sizeBytes = bodyData.byteLength;
-    const url = this.getObjectUrl(storageKey);
+    const disposition = contentDispositionFor(mimeType, input.filename);
 
-    if (this.s3Client) {
-      try {
-        if (typeof this.s3Client.send === 'function') {
-          await this.s3Client.send({
-            input: {
-              Bucket: this.bucket,
-              Key: storageKey,
-              Body: bodyData,
-              ContentType: mimeType
-            }
-          });
-        } else if (typeof this.s3Client.putObject === 'function') {
-          await this.s3Client.putObject({
-            Bucket: this.bucket,
-            Key: storageKey,
-            Body: bodyData,
-            ContentType: mimeType
-          });
-        }
-      } catch {
-        // Fallback
-      }
-    }
+    await client.send(
+      new commands.PutObjectCommand({
+        Bucket: this.bucket,
+        Key: storageKey,
+        Body: body,
+        ContentType: mimeType,
+        ...(disposition ? { ContentDisposition: disposition } : {})
+      })
+    );
 
-    return {
-      storageKey,
-      url,
-      sizeBytes,
-      mimeType
-    };
+    return { storageKey, url: await this.getDownloadUrl(storageKey), sizeBytes: body.byteLength, mimeType };
   }
 
+  /** Deletes an object. S3 deletes are idempotent, so a missing object still returns `true`. */
   async delete(storageKey: string): Promise<boolean> {
-    if (this.s3Client) {
-      try {
-        if (typeof this.s3Client.send === 'function') {
-          await this.s3Client.send({
-            input: {
-              Bucket: this.bucket,
-              Key: storageKey
-            }
-          });
-          return true;
-        } else if (typeof this.s3Client.deleteObject === 'function') {
-          await this.s3Client.deleteObject({
-            Bucket: this.bucket,
-            Key: storageKey
-          });
-          return true;
-        }
-      } catch {
-        return false;
-      }
-    }
+    const { client, commands } = this.requireClient('delete');
+    await client.send(new commands.DeleteObjectCommand({ Bucket: this.bucket, Key: storageKey }));
     return true;
   }
 
   async getDownloadUrl(storageKey: string): Promise<string> {
+    if (this.config.signedDownloads) {
+      const command = new this.config.commands!.GetObjectCommand!({ Bucket: this.bucket, Key: storageKey });
+      return this.config.presign!(command, { expiresIn: this.config.downloadUrlExpiresIn ?? 3600 });
+    }
     return this.getObjectUrl(storageKey);
   }
 
   async getPresignedUploadUrl(options: PresignedUrlOptions): Promise<PresignedUploadResult> {
-    const storageKey = options.storageKey;
-    const uploadUrl = this.getObjectUrl(storageKey);
-
-    const headers: Record<string, string> = {};
-    if (options.contentType) {
-      headers['Content-Type'] = options.contentType;
+    if (!this.config.presign || !this.config.commands) {
+      throw new Error('S3StorageAdapter cannot presign uploads: configure "presign" and "commands".');
     }
-
+    const command = new this.config.commands.PutObjectCommand({
+      Bucket: this.bucket,
+      Key: options.storageKey,
+      ...(options.contentType ? { ContentType: options.contentType } : {})
+    });
+    const uploadUrl = await this.config.presign(command, { expiresIn: options.expiresInSeconds ?? 900 });
     return {
       uploadUrl,
-      storageKey,
+      storageKey: options.storageKey,
       method: 'PUT',
-      headers
+      // The signature covers Content-Type, so the uploader must send exactly this header.
+      headers: options.contentType ? { 'Content-Type': options.contentType } : {}
     };
   }
 }

package/src/storage/storage.test.ts

@@ -42,43 +42,85 @@ describe('Storage Adapters', () => {
   });
 
   describe('S3StorageAdapter', () => {
-    it('generates correct URLs and handles duck-typed client calls', async () => {
-      let sentCommand: any = null;
-      const mockClient = {
-        send: async (cmd: any) => {
-          sentCommand = cmd;
-          return {};
-        }
-      };
-
-      const s3 = new S3StorageAdapter({
+    // Stand-ins for @aws-sdk/client-s3 command classes: they just record their input
+    class PutObjectCommand { constructor(public input: Record<string, unknown>) {} }
+    class DeleteObjectCommand { constructor(public input: Record<string, unknown>) {} }
+    class GetObjectCommand { constructor(public input: Record<string, unknown>) {} }
+    const commands = { PutObjectCommand, DeleteObjectCommand, GetObjectCommand };
+
+    function setup(send: (command: any) => Promise<unknown> = async () => ({})) {
+      const sent: any[] = [];
+      const presigned: Array<{ command: any; expiresIn: number }> = [];
+      const adapter = new S3StorageAdapter({
         bucket: 'my-project-bucket',
         region: 'eu-west-1',
-        s3Client: mockClient
+        client: { send: async (command) => { sent.push(command); return send(command); } },
+        commands,
+        presign: async (command, { expiresIn }) => {
+          presigned.push({ command, expiresIn });
+          return `https://signed.example/${(command as any).input.Key}?X-Amz-Expires=${expiresIn}`;
+        }
       });
+      return { adapter, sent, presigned };
+    }
 
-      const res = await s3.upload({
-        filename: 'spec.pdf',
-        data: new Uint8Array([1, 2, 3, 4]),
-        mimeType: 'application/pdf',
-        pathPrefix: 'docs'
-      });
+    it('uploads with a real command object and returns the object URL', async () => {
+      const { adapter, sent } = setup();
+      const res = await adapter.upload({ filename: 'spec.pdf', data: new Uint8Array([1, 2, 3, 4]), mimeType: 'application/pdf', pathPrefix: 'docs' });
 
-      expect(res.storageKey).toContain('docs/');
-      expect(res.storageKey).toContain('spec.pdf');
+      expect(res.storageKey).toMatch(/^docs\/\d+_[0-9a-f]{12}_spec\.pdf$/);
+      expect(res.sizeBytes).toBe(4);
       expect(res.url).toBe(`https://my-project-bucket.s3.eu-west-1.amazonaws.com/${res.storageKey}`);
-      expect(sentCommand).toBeDefined();
-      expect(sentCommand.input.Bucket).toBe('my-project-bucket');
+      expect(sent[0]).toBeInstanceOf(PutObjectCommand);
+      expect(sent[0].input).toMatchObject({ Bucket: 'my-project-bucket', Key: res.storageKey, ContentType: 'application/pdf' });
+      expect(sent[0].input.ContentDisposition).toBeUndefined();
+
+      expect(await adapter.delete(res.storageKey)).toBe(true);
+      expect(sent[1]).toBeInstanceOf(DeleteObjectCommand);
+    });
 
-      const presigned = await s3.getPresignedUploadUrl({
-        storageKey: 'uploads/file.zip',
-        contentType: 'application/zip'
+    it('forces active content to download', async () => {
+      const { adapter, sent } = setup();
+      await adapter.upload({ filename: 'x.svg', data: '<svg/>', mimeType: 'image/svg+xml', encoding: 'utf-8' });
+      expect(sent[0].input.ContentDisposition).toBe('attachment; filename="x.svg"');
+    });
+
+    it('propagates S3 errors instead of reporting success', async () => {
+      const { adapter } = setup(async () => {
+        throw new Error('AccessDenied');
       });
-      expect(presigned.uploadUrl).toContain('my-project-bucket');
-      expect(presigned.headers?.['Content-Type']).toBe('application/zip');
+      await expect(adapter.upload({ filename: 'a.txt', data: 'x' })).rejects.toThrow('AccessDenied');
+      await expect(adapter.delete('a.txt')).rejects.toThrow('AccessDenied');
+    });
 
-      const deleted = await s3.delete(res.storageKey);
-      expect(deleted).toBe(true);
+    it('refuses to upload or presign without the AWS pieces', async () => {
+      const bare = new S3StorageAdapter({ bucket: 'b' });
+      await expect(bare.upload({ filename: 'a.txt', data: 'x' })).rejects.toThrow(/configure "client"/);
+      await expect(bare.getPresignedUploadUrl({ storageKey: 'k' })).rejects.toThrow(/presign/);
+      expect(() => new S3StorageAdapter({ bucket: 'b', client: { send: async () => ({}) } })).toThrow(/commands/);
+    });
+
+    it('presigns uploads through the provided signer, covering the content type', async () => {
+      const { adapter, presigned } = setup();
+      const result = await adapter.getPresignedUploadUrl({ storageKey: 'projects/p1/file.zip', contentType: 'application/zip', expiresInSeconds: 60 });
+
+      expect(result.uploadUrl).toBe('https://signed.example/projects/p1/file.zip?X-Amz-Expires=60');
+      expect(result.headers).toEqual({ 'Content-Type': 'application/zip' });
+      expect(presigned[0].command).toBeInstanceOf(PutObjectCommand);
+      expect(presigned[0].command.input).toMatchObject({ Key: 'projects/p1/file.zip', ContentType: 'application/zip' });
+    });
+
+    it('serves signed download URLs for private buckets', async () => {
+      const presign = async (command: any, { expiresIn }: { expiresIn: number }) => `https://signed.example/get/${command.input.Key}?e=${expiresIn}`;
+      const adapter = new S3StorageAdapter({ bucket: 'b', client: { send: async () => ({}) }, commands, presign, signedDownloads: true });
+      expect(await adapter.getDownloadUrl('k')).toBe('https://signed.example/get/k?e=3600');
+    });
+
+    it('rejects path prefixes that escape their directory', async () => {
+      const { adapter } = setup();
+      for (const pathPrefix of ['../other', 'projects/../../x', '/abs', 'a//b', 'bad prefix']) {
+        await expect(adapter.upload({ filename: 'a.txt', data: 'x', pathPrefix })).rejects.toThrow(/Invalid storage path prefix/);
+      }
     });
   });
 
@@ -89,6 +131,7 @@ describe('Storage Adapters', () => {
         bucket: mockStorage,
         bucketName: 'my-app.appspot.com'
       });
+      expect(() => new FirebaseStorageAdapter()).toThrow(/requires a "bucket"/);
 
       const uploadResult = await adapter.upload({
         filename: 'architecture.png',
@@ -213,4 +256,19 @@ describe('Storage Adapters', () => {
       expect(reviewAttachments.length).toBe(0);
     });
   });
+
+  it('stores uploads made through an actor view under the project prefix', async () => {
+    const engine = new CriticalPathEngine({ fileStorage: new InMemoryFileStore() });
+    const project = await engine.createProject({ name: 'Uploads' });
+    const task = await engine.createTask({ projectId: project.id, title: 'T' });
+
+    const attachment = await engine.withActor({ userId: 'u1' }).uploadAttachmentFile({ taskId: task.id, filename: 'notes.txt', data: 'hi', encoding: 'utf-8' });
+    expect(attachment.storageKey?.startsWith(`projects/${project.id}/`)).toBe(true);
+    expect(attachment.uploaderId).toBe('u1');
+
+    await expect(
+      engine.withActor({ userId: 'u1' }).uploadAttachmentFile({ filename: 'orphan.txt', data: 'x' })
+    ).rejects.toThrow(/must reference a project/);
+  });
 });
+