@critical-path/core 0.29.0 → 0.31.0

package/src/storage/firebase-storage.ts

@@ -5,7 +5,7 @@ import type {
   PresignedUrlOptions,
   PresignedUploadResult
 } from '../types/index.js';
-import { normalizeUploadData } from './file-storage.js';
+import { buildStorageKey, contentDispositionFor, normalizeUploadData } from './file-storage.js';
 
 export interface FirebaseStorageBucketInterface {
   name?: string;
@@ -90,7 +90,11 @@ export class FirebaseStorageAdapter implements FileStorageAdapter {
   private publicUrlBase?: string;
 
   constructor(config: FirebaseStorageConfig = {}) {
-    this.bucket = config.bucket || new InMemoryFirebaseStorageMock(config.bucketName || 'default-bucket');
+    if (!config.bucket) {
+      // Never fall back to an in-memory mock silently: files would vanish on restart.
+      throw new Error('FirebaseStorageAdapter requires a "bucket" (e.g. getStorage().bucket()). Use InMemoryFirebaseStorageMock in tests.');
+    }
+    this.bucket = config.bucket;
     this.bucketName = config.bucketName || this.bucket.name || 'default-bucket';
     if (this.bucket && config.bucketName && this.bucket.name !== config.bucketName) {
       this.bucket.name = config.bucketName;
@@ -107,10 +111,7 @@ export class FirebaseStorageAdapter implements FileStorageAdapter {
   }
 
   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}`;
+    const storageKey = buildStorageKey(input.pathPrefix, input.filename);
 
     const bodyData = normalizeUploadData(input.data, input.encoding, input.mimeType);
     const mimeType = input.mimeType || 'application/octet-stream';
@@ -124,6 +125,7 @@ export class FirebaseStorageAdapter implements FileStorageAdapter {
     await fileRef.save(bodyData, {
       metadata: {
         contentType: mimeType,
+        ...(contentDispositionFor(mimeType, input.filename) ? { contentDisposition: contentDispositionFor(mimeType, input.filename) } : {}),
         metadata: {
           firebaseStorageDownloadTokens: downloadToken
         }
@@ -201,12 +203,7 @@ export class FirebaseStorageAdapter implements FileStorageAdapter {
       };
     }
 
-    // Fallback to direct public upload url
-    return {
-      uploadUrl: this.getPublicUrl(storageKey),
-      storageKey,
-      method: 'PUT',
-      headers: options.contentType ? { 'Content-Type': options.contentType } : {}
-    };
+    // A public URL is not an upload credential; refuse rather than hand out a URL that cannot work.
+    throw new Error('FirebaseStorageAdapter cannot presign uploads: the bucket does not support getSignedUrl.');
   }
 }

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/);
+  });
 });
+

package/src/store/firebase.ts

@@ -1,4 +1,5 @@
 import type { StorageAdapter } from './index.js';
+import { matchesActivityQuery, matchesTaskQuery, paginate, type ActivityQuery, type Page, type TaskQuery } from './query.js';
 import type {
   Project,
   Task,
@@ -344,6 +345,12 @@ export class FirebaseStore implements StorageAdapter {
     return snap.docs.map((doc) => ({ ...doc.data(), id: doc.id }));
   }
 
+  /** Pushes down the project filter; remaining filters and pagination are applied in memory. */
+  async queryTasks(query: TaskQuery): Promise<Page<Task>> {
+    const tasks = (await this.getTasks(query.projectId)).filter((t) => matchesTaskQuery(t, query));
+    return paginate(tasks, (t) => t.createdAt, 'asc', query.limit, query.cursor);
+  }
+
   async getTask(id: string): Promise<Task | null> {
     const snap = await this.db.collection('tasks').doc(id).get();
     if (!snap.exists) return null;
@@ -526,6 +533,13 @@ export class FirebaseStore implements StorageAdapter {
     return snap.docs.map((doc) => ({ ...doc.data(), id: doc.id }));
   }
 
+  async queryActivities(query: ActivityQuery): Promise<Page<Activity>> {
+    const activities = (await this.getActivities({ projectId: query.projectId, taskId: query.taskId })).filter((a) =>
+      matchesActivityQuery(a, query)
+    );
+    return paginate(activities, (a) => a.createdAt, 'desc', query.limit, query.cursor);
+  }
+
   async logActivity(activity: Omit<Activity, 'id' | 'createdAt'>): Promise<Activity> {
     const docRef = this.db.collection('activities').doc();
     const now = new Date().toISOString();

package/src/store/index.ts

@@ -18,6 +18,16 @@ import type {
   CreateDeliverableInput
 } from '../types/index.js';
 import { generateProjectKey } from '../utils/key.js';
+import {
+  matchesActivityQuery,
+  matchesTaskQuery,
+  paginate,
+  type ActivityQuery,
+  type Page,
+  type TaskQuery
+} from './query.js';
+
+export * from './query.js';
 
 export interface ProjectRepository {
   getProjects(): Promise<Project[]>;
@@ -37,6 +47,8 @@ export interface WorkflowRepository {
 
 export interface TaskRepository {
   getTasks(projectId?: string): Promise<Task[]>;
+  /** Filtered, paginated tasks ordered by `(createdAt, id)` ascending. */
+  queryTasks(query: TaskQuery): Promise<Page<Task>>;
   getTask(id: string): Promise<Task | null>;
   createTask(task: Omit<Task, 'id' | 'createdAt' | 'updatedAt'>): Promise<Task>;
   updateTask(id: string, updates: Partial<Task>): Promise<Task | null>;
@@ -86,6 +98,8 @@ export interface AttachmentRepository {
 
 export interface ActivityRepository {
   getActivities(filter?: { projectId?: string; taskId?: string }): Promise<Activity[]>;
+  /** Paginated activity feed ordered by `(createdAt, id)` descending (newest first). */
+  queryActivities(query: ActivityQuery): Promise<Page<Activity>>;
   logActivity(activity: Omit<Activity, 'id' | 'createdAt'>): Promise<Activity>;
 }
 
@@ -234,6 +248,11 @@ export class InMemoryStore implements StorageAdapter {
     return all;
   }
 
+  async queryTasks(query: TaskQuery): Promise<Page<Task>> {
+    const tasks = Array.from(this.tasks.values()).filter((t) => matchesTaskQuery(t, query));
+    return paginate(tasks, (t) => t.createdAt, 'asc', query.limit, query.cursor);
+  }
+
   async getTask(id: string): Promise<Task | null> {
     return this.tasks.get(id) || null;
   }
@@ -507,6 +526,11 @@ export class InMemoryStore implements StorageAdapter {
     });
   }
 
+  async queryActivities(query: ActivityQuery): Promise<Page<Activity>> {
+    const activities = this.activities.filter((a) => matchesActivityQuery(a, query));
+    return paginate(activities, (a) => a.createdAt, 'desc', query.limit, query.cursor);
+  }
+
   async logActivity(activity: Omit<Activity, 'id' | 'createdAt'>): Promise<Activity> {
     const id = `act_${Math.random().toString(36).substring(2, 9)}`;
     const newAct: Activity = { ...activity, id, createdAt: new Date().toISOString() };

package/src/store/query.test.ts

@@ -0,0 +1,110 @@
+import { describe, it, expect } from 'vitest';
+import {
+  CriticalPathEngine,
+  InMemoryStore,
+  SQLiteStore,
+  FirebaseStore,
+  InMemoryFirestoreMock,
+  ValidationError,
+  createRolePolicy,
+  MAX_PAGE_SIZE,
+  type StorageAdapter,
+  type Task
+} from '../index.js';
+
+const stores: Array<[string, () => StorageAdapter]> = [
+  ['InMemoryStore', () => new InMemoryStore()],
+  ['SQLiteStore', () => new SQLiteStore({ filename: ':memory:' })],
+  ['FirebaseStore', () => new FirebaseStore({ db: new InMemoryFirestoreMock() })]
+];
+
+describe.each(stores)('task and activity queries (%s)', (_name, makeStore) => {
+  async function setup() {
+    const engine = new CriticalPathEngine({ store: makeStore() });
+    const project = await engine.createProject({ name: 'Query' });
+    const other = await engine.createProject({ name: 'Other' });
+    const sprint = await engine.createIteration({ projectId: project.id, name: 'S1', status: 'active' });
+    const parent = await engine.createTask({ projectId: project.id, title: 'Parent', status: 'in_progress', priority: 'high', assigneeId: 'ana' });
+    const child = await engine.createTask({ projectId: project.id, title: 'Child', parentId: parent.id, status: 'todo', priority: 'low', iterationId: sprint.id });
+    const shared = await engine.createTask({
+      projectId: project.id,
+      title: 'Shared',
+      status: 'done',
+      priority: 'high',
+      assignees: [{ id: 'ana', type: 'user' }, { id: 'ben', type: 'user' }]
+    });
+    const elsewhere = await engine.createTask({ projectId: other.id, title: 'Elsewhere', assigneeId: 'ana' });
+    return { engine, project, other, sprint, parent, child, shared, elsewhere };
+  }
+  const titles = (tasks: Task[]) => tasks.map((t) => t.title).sort();
+
+  it('filters by status, priority, assignee (including assignees), iteration and parent', async () => {
+    const { engine, project, sprint, parent } = await setup();
+    const q = (query: object) => engine.queryTasks({ projectId: project.id, ...query }).then((p) => titles(p.items));
+
+    expect(await q({ status: ['todo', 'done'] })).toEqual(['Child', 'Shared']);
+    expect(await q({ priority: ['high'] })).toEqual(['Parent', 'Shared']);
+    expect(await q({ assigneeId: 'ana' })).toEqual(['Parent', 'Shared']);
+    expect(await q({ assigneeId: 'ben' })).toEqual(['Shared']);
+    expect(await q({ iterationId: sprint.id })).toEqual(['Child']);
+    expect(await q({ parentId: parent.id })).toEqual(['Child']);
+    expect(await q({ parentId: null })).toEqual(['Parent', 'Shared']);
+    expect(titles((await engine.queryTasks({ assigneeId: 'ana' })).items)).toEqual(['Elsewhere', 'Parent', 'Shared']);
+  });
+
+  it('pages through every task exactly once, oldest first', async () => {
+    const { engine, project } = await setup();
+    for (let i = 0; i < 12; i++) await engine.createTask({ projectId: project.id, title: `Bulk ${i}` });
+
+    const seen: Task[] = [];
+    let cursor: string | undefined;
+    do {
+      const page = await engine.queryTasks({ projectId: project.id, limit: 5, cursor });
+      expect(page.items.length).toBeLessThanOrEqual(5);
+      seen.push(...page.items);
+      cursor = page.nextCursor;
+    } while (cursor);
+
+    expect(seen).toHaveLength(15);
+    expect(new Set(seen.map((t) => t.id)).size).toBe(15);
+    const keys = seen.map((t) => `${t.createdAt}|${t.id}`);
+    expect([...keys].sort()).toEqual(keys);
+  });
+
+  it('pages the activity feed newest first', async () => {
+    const { engine, project } = await setup();
+    const all = (await engine.queryActivities({ projectId: project.id, limit: MAX_PAGE_SIZE })).items;
+    expect(all.length).toBeGreaterThan(3);
+    const keys = all.map((a) => `${a.createdAt}|${a.id}`);
+    expect([...keys].sort().reverse()).toEqual(keys);
+
+    const first = await engine.queryActivities({ projectId: project.id, limit: 2 });
+    const second = await engine.queryActivities({ projectId: project.id, limit: 2, cursor: first.nextCursor });
+    expect([...first.items, ...second.items].map((a) => a.id)).toEqual(all.slice(0, 4).map((a) => a.id));
+  });
+
+  it('rejects malformed cursors and clamps page sizes', async () => {
+    const { engine, project } = await setup();
+    await expect(engine.queryTasks({ projectId: project.id, cursor: 'not-a-cursor' })).rejects.toThrow(ValidationError);
+    expect((await engine.queryTasks({ projectId: project.id, limit: 0 })).items).toHaveLength(1);
+    expect((await engine.queryTasks({ projectId: project.id, limit: 10_000 })).items).toHaveLength(3);
+  });
+});
+
+describe('query authorization', () => {
+  it('limits cross-project queries and activity feeds to readable projects', async () => {
+    const engine = new CriticalPathEngine({ authorize: createRolePolicy() });
+    const mine = await engine.createProject({ name: 'Mine', members: [{ userId: 'ana', role: 'viewer' }] });
+    const secret = await engine.createProject({ name: 'Secret' });
+    await engine.createTask({ projectId: mine.id, title: 'Visible' });
+    await engine.createTask({ projectId: secret.id, title: 'Hidden' });
+    const ana = engine.withActor({ userId: 'ana' });
+
+    expect((await ana.queryTasks()).items.map((t) => t.title)).toEqual(['Visible']);
+    expect((await ana.queryTasks({ projectId: secret.id })).items).toEqual([]);
+    expect((await ana.queryTasks({ projectIds: [mine.id, secret.id] })).items.map((t) => t.title)).toEqual(['Visible']);
+    const feed = (await ana.queryActivities()).items;
+    expect(feed.length).toBeGreaterThan(0);
+    expect(feed.every((a) => a.projectId === mine.id)).toBe(true);
+  });
+});