@critical-path/core 0.24.0 → 0.26.0

package/src/index.test.ts

@@ -485,11 +485,7 @@ describe('CriticalPathEngine Core Tests', () => {
     });
 
     // Update with explicit actor (e.g. human user updating an assigned agent task)
-    await engine.updateTask(task.id, {
-      status: 'in_progress',
-      actorId: 'user_human_42',
-      actorName: 'Jack James'
-    });
+    await engine.updateTask(task.id, { status: 'in_progress' }, { actorId: 'user_human_42', actorName: 'Jack James' });
 
     const activities = await engine.store.getActivities({ taskId: task.id });
     const statusActivity = activities.find((a) => a.action === 'task.status_changed');

package/src/schemas/index.ts

@@ -4,8 +4,9 @@
  * Exposed from `@critical-path/core/schemas` (not the package root) so browser bundles of core do
  * not pull in zod. Create schemas omit server-assigned fields (`id`, `createdAt`, `updatedAt`, task
  * `key`); update schemas additionally make every field optional and omit the owning `projectId`.
- * Unknown keys are stripped rather than rejected, so older clients that send whole objects keep
- * working while protected fields are never written.
+ * Schemas are strict: unknown or server-assigned keys are rejected with a 400 rather than ignored.
+ * Identity (authors, reactors, uploaders, time-entry users) is never taken from payloads; it comes
+ * from the caller resolved by the server (see `CriticalPathEngine.withActor`).
  */
 import { z } from 'zod';
 import { ValidationError, type ValidationIssue } from '../domain/errors.js';
@@ -25,36 +26,41 @@ export function parsePayload<S extends z.ZodTypeAny>(schema: S, data: unknown):
   throw new ValidationError(`Invalid request body: ${summary}`, issues);
 }
 
+/** Objects reject unknown keys so typos and protected fields surface as 400s. */
+function strictObject<T extends z.ZodRawShape>(shape: T) {
+  return z.object(shape).strict();
+}
+
 const isoString = z.string();
 const nonEmpty = z.string().min(1);
 
 export const SemanticStatusSchema = z.enum(['not_started', 'in_progress', 'completed', 'canceled']);
 export const AuthorTypeSchema = z.enum(['user', 'agent', 'system']);
 
-export const StatusDefinitionSchema = z.object({
+export const StatusDefinitionSchema = strictObject({
   key: nonEmpty,
   label: z.string(),
   category: SemanticStatusSchema
 });
 
-export const WorkScheduleSchema = z.object({
+export const WorkScheduleSchema = strictObject({
   id: z.string().optional(),
   name: z.string().optional(),
   timezone: z.string().optional(),
   defaultHoursPerDay: z.number().nonnegative().optional(),
   days: z.array(
-    z.object({
+    strictObject({
       dayOfWeek: z.number().int().min(0).max(6),
       isWorkingDay: z.boolean(),
-      hours: z.array(z.object({ start: z.string(), end: z.string() })).optional()
+      hours: z.array(strictObject({ start: z.string(), end: z.string() })).optional()
     })
   ),
   holidays: z
-    .array(z.object({ date: z.string(), name: z.string().optional(), halfDay: z.boolean().optional() }))
+    .array(strictObject({ date: z.string(), name: z.string().optional(), halfDay: z.boolean().optional() }))
     .optional()
 });
 
-export const CustomFieldDefinitionSchema = z.object({
+export const CustomFieldDefinitionSchema = strictObject({
   id: z.string(),
   key: nonEmpty,
   label: z.string(),
@@ -64,7 +70,7 @@ export const CustomFieldDefinitionSchema = z.object({
   defaultValue: z.unknown().optional()
 });
 
-export const TaskTypeDefinitionSchema = z.object({
+export const TaskTypeDefinitionSchema = strictObject({
   key: nonEmpty,
   label: z.string(),
   description: z.string().optional(),
@@ -78,13 +84,13 @@ const metadata = z.record(z.unknown());
 
 // --- Workflows ---
 
-export const CreateWorkflowSchema = z.object({
+export const CreateWorkflowSchema = strictObject({
   name: nonEmpty,
   description: z.string().optional(),
   statuses: z.array(StatusDefinitionSchema),
   transitions: z
     .array(
-      z.object({
+      strictObject({
         id: z.string().optional(),
         name: z.string().optional(),
         fromStatusKey: z.string(),
@@ -100,18 +106,20 @@ export const UpdateWorkflowSchema = CreateWorkflowSchema.partial();
 
 // --- Projects ---
 
-export const CreateProjectSchema = z.object({
+export const CreateProjectSchema = strictObject({
   key: z.string().optional(),
   name: nonEmpty,
   description: z.string().optional(),
   ownerId: z.string().optional(),
-  members: z.array(z.string()).optional(),
+  members: z
+    .array(strictObject({ userId: nonEmpty, role: z.enum(['admin', 'project_manager', 'contributor', 'viewer']) }))
+    .optional(),
   teamIds: z.array(z.string()).optional(),
   workflowId: z.string().optional(),
   taskTypes: z.array(TaskTypeDefinitionSchema).optional(),
   statusDefinitions: z.array(StatusDefinitionSchema).optional(),
   priorityDefinitions: z
-    .array(z.object({ key: z.string(), label: z.string(), level: z.number().optional() }))
+    .array(strictObject({ key: z.string(), label: z.string(), level: z.number().optional() }))
     .optional(),
   customFieldDefinitions: z.array(CustomFieldDefinitionSchema).optional(),
   schedule: WorkScheduleSchema.optional(),
@@ -132,7 +140,7 @@ const taskFields = {
   assigneeId: z.string().optional(),
   assignees: z
     .array(
-      z.object({
+      strictObject({
         id: z.string(),
         name: z.string().optional(),
         role: z.string().optional(),
@@ -169,7 +177,7 @@ const taskFields = {
   tags: z.array(z.string()).optional(),
   todos: z
     .array(
-      z.object({
+      strictObject({
         id: z.string(),
         title: z.string(),
         completed: z.boolean(),
@@ -182,23 +190,13 @@ const taskFields = {
   parentId: z.string().optional()
 };
 
-export const CreateTaskSchema = z.object({ projectId: nonEmpty, ...taskFields });
-
-/** Actor fields accepted on task updates; ignored when the server resolves the caller. */
-const actorClaimFields = {
-  actorId: z.string().optional(),
-  actorName: z.string().optional(),
-  actorType: z.string().optional(),
-  actor: z
-    .object({ userId: z.string(), username: z.string().optional(), actorType: z.string().optional() })
-    .optional()
-};
+export const CreateTaskSchema = strictObject({ projectId: nonEmpty, ...taskFields });
 
-export const UpdateTaskSchema = z.object(taskFields).partial().extend(actorClaimFields);
+export const UpdateTaskSchema = strictObject(taskFields).partial();
 
 // --- Dependencies ---
 
-export const CreateDependencySchema = z.object({
+export const CreateDependencySchema = strictObject({
   dependsOnTaskId: nonEmpty,
   type: z.enum(['blocking', 'blocked_by', 'relates_to']).default('blocking')
 });
@@ -218,12 +216,12 @@ const deliverableFields = {
   outputUrls: z.array(z.string()).optional(),
   customFields: customFields.optional()
 };
-export const CreateDeliverableSchema = z.object({ projectId: nonEmpty, ...deliverableFields });
-export const UpdateDeliverableSchema = z.object(deliverableFields).partial();
+export const CreateDeliverableSchema = strictObject({ projectId: nonEmpty, ...deliverableFields });
+export const UpdateDeliverableSchema = strictObject(deliverableFields).partial();
 
 // --- Teams ---
 
-export const CreateTeamSchema = z.object({
+export const CreateTeamSchema = strictObject({
   name: nonEmpty,
   description: z.string().optional(),
   leaderId: z.string().optional(),
@@ -242,8 +240,8 @@ const containerFields = {
   type: z.string().optional(),
   color: z.string().optional()
 };
-export const CreateContainerSchema = z.object({ projectId: nonEmpty, ...containerFields });
-export const UpdateContainerSchema = z.object(containerFields).partial();
+export const CreateContainerSchema = strictObject({ projectId: nonEmpty, ...containerFields });
+export const UpdateContainerSchema = strictObject(containerFields).partial();
 
 // --- Iterations ---
 
@@ -255,18 +253,15 @@ const iterationFields = {
   endDate: isoString.optional(),
   status: z.enum(['planning', 'active', 'completed']).default('planning')
 };
-export const CreateIterationSchema = z.object({ projectId: nonEmpty, ...iterationFields });
+export const CreateIterationSchema = strictObject({ projectId: nonEmpty, ...iterationFields });
 export const UpdateIterationSchema = z
   .object({ ...iterationFields, status: z.enum(['planning', 'active', 'completed']) })
   .partial();
 
 // --- Comments & Reactions ---
 
-export const CreateCommentSchema = z.object({
+export const CreateCommentSchema = strictObject({
   taskId: nonEmpty,
-  /** Required unless the server resolves the caller, in which case it is replaced. */
-  authorId: z.string().optional(),
-  authorType: AuthorTypeSchema.optional(),
   parentId: z.string().optional(),
   content: nonEmpty,
   mentions: z.array(z.string()).optional(),
@@ -276,10 +271,8 @@ export const UpdateCommentSchema = z
   .object({ content: nonEmpty, mentions: z.array(z.string()), metadata })
   .partial();
 
-export const CommentReactionSchema = z.object({
-  emoji: nonEmpty,
-  /** Required unless the server resolves the caller, in which case it is replaced. */
-  userId: z.string().optional()
+export const CommentReactionSchema = strictObject({
+  emoji: nonEmpty
 });
 
 // --- Attachments ---
@@ -288,14 +281,11 @@ const attachmentLinks = {
   taskId: z.string().optional(),
   projectId: z.string().optional(),
   commentId: z.string().optional(),
-  /** Required unless the server resolves the caller, in which case it is replaced. */
-  uploaderId: z.string().optional(),
-  uploaderType: AuthorTypeSchema.optional(),
   artifactType: z.enum(['plan', 'spec', 'deliverable', 'review', 'general']).optional(),
   metadata: metadata.optional()
 };
 
-export const CreateAttachmentSchema = z.object({
+export const CreateAttachmentSchema = strictObject({
   ...attachmentLinks,
   filename: nonEmpty,
   // Linked (rather than uploaded) files often have no known type or size.
@@ -305,7 +295,7 @@ export const CreateAttachmentSchema = z.object({
   storageKey: z.string().optional()
 });
 
-export const UploadAttachmentSchema = z.object({
+export const UploadAttachmentSchema = strictObject({
   ...attachmentLinks,
   filename: nonEmpty,
   data: z.string(),
@@ -314,7 +304,9 @@ export const UploadAttachmentSchema = z.object({
   encoding: z.enum(['base64', 'utf-8', 'binary']).optional()
 });
 
-export const PresignAttachmentSchema = z.object({
+export const PresignAttachmentSchema = strictObject({
+  /** Project the upload belongs to; scoped callers may only write under `projects/<projectId>/`. */
+  projectId: nonEmpty,
   storageKey: nonEmpty,
   expiresInSeconds: z.number().int().positive().optional(),
   contentType: z.string().optional()
@@ -322,12 +314,11 @@ export const PresignAttachmentSchema = z.object({
 
 // --- Time Tracking ---
 
-export const LogTimeSchema = z.object({
+export const LogTimeSchema = strictObject({
   taskId: nonEmpty,
   hours: z.number().positive(),
   isBillable: z.boolean().optional(),
   description: z.string().optional(),
-  userId: z.string().optional(),
   loggedAt: isoString.optional()
 });
 
@@ -335,3 +326,28 @@ export type CreateTaskPayload = z.infer<typeof CreateTaskSchema>;
 export type UpdateTaskPayload = z.infer<typeof UpdateTaskSchema>;
 export type CreateProjectPayload = z.infer<typeof CreateProjectSchema>;
 export type UpdateProjectPayload = z.infer<typeof UpdateProjectSchema>;
+
+/** Request body types (before defaults are applied), for typed API clients. */
+export type CreateWorkflowBody = z.input<typeof CreateWorkflowSchema>;
+export type UpdateWorkflowBody = z.input<typeof UpdateWorkflowSchema>;
+export type CreateProjectBody = z.input<typeof CreateProjectSchema>;
+export type UpdateProjectBody = z.input<typeof UpdateProjectSchema>;
+export type CreateTaskBody = z.input<typeof CreateTaskSchema>;
+export type UpdateTaskBody = z.input<typeof UpdateTaskSchema>;
+export type CreateDependencyBody = z.input<typeof CreateDependencySchema>;
+export type CreateDeliverableBody = z.input<typeof CreateDeliverableSchema>;
+export type UpdateDeliverableBody = z.input<typeof UpdateDeliverableSchema>;
+export type CreateTeamBody = z.input<typeof CreateTeamSchema>;
+export type UpdateTeamBody = z.input<typeof UpdateTeamSchema>;
+export type CreateContainerBody = z.input<typeof CreateContainerSchema>;
+export type UpdateContainerBody = z.input<typeof UpdateContainerSchema>;
+export type CreateIterationBody = z.input<typeof CreateIterationSchema>;
+export type UpdateIterationBody = z.input<typeof UpdateIterationSchema>;
+export type CreateCommentBody = z.input<typeof CreateCommentSchema>;
+export type UpdateCommentBody = z.input<typeof UpdateCommentSchema>;
+export type CommentReactionBody = z.input<typeof CommentReactionSchema>;
+export type CreateAttachmentBody = z.input<typeof CreateAttachmentSchema>;
+export type UploadAttachmentBody = z.input<typeof UploadAttachmentSchema>;
+export type PresignAttachmentBody = z.input<typeof PresignAttachmentSchema>;
+export type LogTimeBody = z.input<typeof LogTimeSchema>;
+

package/src/schemas/schemas.test.ts

@@ -46,14 +46,17 @@ type SameKeys<Schema, Expected> = [Exclude<keyof Schema, keyof Expected>, Exclud
   : { extraInSchema: Exclude<keyof Schema, keyof Expected>; missingFromSchema: Exclude<keyof Expected, keyof Schema> };
 
 type Infer<S extends z.ZodTypeAny> = z.infer<S>;
-type ServerAssigned = 'id' | 'createdAt' | 'updatedAt';
-type ActorClaims = 'actorId' | 'actorName' | 'actorType' | 'actor';
+// tenantId is stamped from the actor by the engine, never accepted from payloads.
+type ServerAssigned = 'id' | 'createdAt' | 'updatedAt' | 'tenantId';
+// Identity is resolved by the server (withActor), never accepted in payloads.
+type CommentIdentity = 'authorId' | 'authorType';
+type UploaderIdentity = 'uploaderId' | 'uploaderType';
 
 const keyChecks: true[] = [
   true as SameKeys<Infer<typeof CreateTaskSchema>, Omit<CreateTaskInput, 'key'>>,
-  true as SameKeys<Omit<Infer<typeof UpdateTaskSchema>, ActorClaims>, Omit<Task, ServerAssigned | 'key' | 'projectId'>>,
+  true as SameKeys<Infer<typeof UpdateTaskSchema>, Omit<Task, ServerAssigned | 'key' | 'projectId'>>,
   // `workflow` is a denormalised copy resolved from `workflowId`, so it is not writable.
-  true as SameKeys<Infer<typeof CreateProjectSchema>, Omit<CreateProjectInput, 'workflow'>>,
+  true as SameKeys<Infer<typeof CreateProjectSchema>, Omit<CreateProjectInput, 'workflow' | 'tenantId'>>,
   true as SameKeys<Infer<typeof UpdateProjectSchema>, Omit<Project, ServerAssigned | 'workflow'>>,
   true as SameKeys<Infer<typeof CreateWorkflowSchema>, Omit<Workflow, ServerAssigned>>,
   true as SameKeys<Infer<typeof CreateDeliverableSchema>, CreateDeliverableInput>,
@@ -63,10 +66,10 @@ const keyChecks: true[] = [
   true as SameKeys<Infer<typeof UpdateContainerSchema>, Omit<TaskContainer, ServerAssigned | 'projectId'>>,
   true as SameKeys<Infer<typeof CreateIterationSchema>, Omit<Iteration, 'id' | 'createdAt'>>,
   // Reactions are managed through the reactions endpoints.
-  true as SameKeys<Infer<typeof CreateCommentSchema>, Omit<Comment, ServerAssigned | 'reactions'>>,
+  true as SameKeys<Infer<typeof CreateCommentSchema>, Omit<Comment, ServerAssigned | 'reactions' | CommentIdentity>>,
   true as SameKeys<Infer<typeof UpdateCommentSchema>, Pick<Comment, 'content' | 'mentions' | 'metadata'>>,
-  true as SameKeys<Infer<typeof CreateAttachmentSchema>, CreateAttachmentInput>,
-  true as SameKeys<Infer<typeof LogTimeSchema>, Omit<TimeEntry, 'id'>>
+  true as SameKeys<Infer<typeof CreateAttachmentSchema>, Omit<CreateAttachmentInput, UploaderIdentity>>,
+  true as SameKeys<Infer<typeof LogTimeSchema>, Omit<TimeEntry, 'id' | 'userId'>>
 ];
 
 describe('request schemas', () => {
@@ -74,16 +77,15 @@ describe('request schemas', () => {
     expect(keyChecks.every(Boolean)).toBe(true);
   });
 
-  it('strip server-assigned and unknown fields', () => {
-    const parsed = UpdateTaskSchema.parse({
-      title: 'ok',
-      id: 'hijack',
-      projectId: 'other',
-      createdAt: '1999-01-01',
-      key: 'X-1',
-      junk: true
-    });
-    expect(parsed).toEqual({ title: 'ok' });
+  it('reject server-assigned, identity and unknown fields', () => {
+    for (const extra of [{ id: 'x' }, { projectId: 'other' }, { createdAt: '1999-01-01' }, { key: 'X-1' }, { junk: true }, { actorId: 'ceo' }]) {
+      const result = UpdateTaskSchema.safeParse({ title: 'ok', ...extra });
+      expect(result.success, JSON.stringify(extra)).toBe(false);
+    }
+    expect(CreateCommentSchema.safeParse({ taskId: 't1', content: 'hi', authorId: 'ceo' }).success).toBe(false);
+    // Nested objects are strict too
+    expect(UpdateTaskSchema.safeParse({ todos: [{ id: '1', title: 'a', completed: false, extra: 1 }] }).success).toBe(false);
+    expect(UpdateTaskSchema.parse({ title: 'ok' })).toEqual({ title: 'ok' });
   });
 
   it('reject wrong types and out-of-range values', () => {

package/src/store/sqlite.ts

@@ -279,6 +279,14 @@ export class SQLiteStore implements StorageAdapter {
     } catch {
       // Column may already exist
     }
+
+    for (const table of ['projects', 'workflows', 'teams']) {
+      try {
+        this.db.exec(`ALTER TABLE ${table} ADD COLUMN tenantId TEXT`);
+      } catch {
+        // Column may already exist
+      }
+    }
   }
 
   // --- Projects ---
@@ -301,8 +309,8 @@ export class SQLiteStore implements StorageAdapter {
     const newProj: Project = { ...project, key, id, createdAt: now, updatedAt: now };
 
     const stmt = this.db.prepare(`
-      INSERT INTO projects (id, key, name, description, ownerId, members, teamIds, workflowId, taskTypes, statusDefinitions, priorityDefinitions, customFieldDefinitions, createdAt, updatedAt)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      INSERT INTO projects (id, key, name, description, ownerId, members, teamIds, workflowId, taskTypes, statusDefinitions, priorityDefinitions, customFieldDefinitions, tenantId, createdAt, updatedAt)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `);
     stmt.run(
       newProj.id,
@@ -317,6 +325,7 @@ export class SQLiteStore implements StorageAdapter {
       JSON.stringify(newProj.statusDefinitions || []),
       JSON.stringify(newProj.priorityDefinitions || []),
       JSON.stringify(newProj.customFieldDefinitions || []),
+      newProj.tenantId ?? null,
       newProj.createdAt,
       newProj.updatedAt
     );
@@ -375,8 +384,8 @@ export class SQLiteStore implements StorageAdapter {
     const newWf: Workflow = { ...workflow, id, createdAt: now, updatedAt: now };
 
     const stmt = this.db.prepare(`
-      INSERT INTO workflows (id, name, description, statuses, transitions, taskTypes, defaultStatusKey, isDefault, createdAt, updatedAt)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      INSERT INTO workflows (id, name, description, statuses, transitions, taskTypes, defaultStatusKey, isDefault, tenantId, createdAt, updatedAt)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `);
     stmt.run(
       newWf.id,
@@ -387,6 +396,7 @@ export class SQLiteStore implements StorageAdapter {
       newWf.taskTypes ? JSON.stringify(newWf.taskTypes) : null,
       newWf.defaultStatusKey || null,
       newWf.isDefault ? 1 : 0,
+      newWf.tenantId ?? null,
       newWf.createdAt,
       newWf.updatedAt
     );
@@ -452,8 +462,8 @@ export class SQLiteStore implements StorageAdapter {
     const newTeam: Team = { ...team, id, createdAt: now, updatedAt: now };
 
     const stmt = this.db.prepare(`
-      INSERT INTO teams (id, name, description, leaderId, memberIds, createdAt, updatedAt)
-      VALUES (?, ?, ?, ?, ?, ?, ?)
+      INSERT INTO teams (id, name, description, leaderId, memberIds, tenantId, createdAt, updatedAt)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
     `);
     stmt.run(
       newTeam.id,
@@ -461,6 +471,7 @@ export class SQLiteStore implements StorageAdapter {
       newTeam.description || null,
       newTeam.leaderId || null,
       JSON.stringify(newTeam.memberIds || []),
+      newTeam.tenantId ?? null,
       newTeam.createdAt,
       newTeam.updatedAt
     );
@@ -1195,6 +1206,7 @@ export class SQLiteStore implements StorageAdapter {
   private mapProject(row: any): Project {
     return {
       ...row,
+      tenantId: row.tenantId ?? undefined,
       workflowId: row.workflowId || undefined,
       taskTypes: row.taskTypes ? JSON.parse(row.taskTypes) : undefined,
       members: row.members ? JSON.parse(row.members) : [],
@@ -1208,6 +1220,7 @@ export class SQLiteStore implements StorageAdapter {
   private mapWorkflow(row: any): Workflow {
     return {
       ...row,
+      tenantId: row.tenantId ?? undefined,
       statuses: row.statuses ? JSON.parse(row.statuses) : [],
       transitions: row.transitions ? JSON.parse(row.transitions) : [],
       taskTypes: row.taskTypes ? JSON.parse(row.taskTypes) : undefined,
@@ -1218,6 +1231,7 @@ export class SQLiteStore implements StorageAdapter {
   private mapTeam(row: any): Team {
     return {
       ...row,
+      tenantId: row.tenantId ?? undefined,
       memberIds: row.memberIds ? JSON.parse(row.memberIds) : []
     };
   }

package/src/types/index.ts

@@ -78,6 +78,8 @@ export interface Team {
   memberIds: string[];
   weeklyCapacityHours?: number;
   schedule?: WorkSchedule;
+  /** Tenant that owns the team. Set by the engine from the creating actor. */
+  tenantId?: string;
   createdAt: string;
   updatedAt: string;
 }
@@ -117,6 +119,8 @@ export interface Workflow {
   taskTypes?: TaskTypeDefinition[];
   defaultStatusKey?: string;
   isDefault?: boolean;
+  /** Tenant that owns the workflow. Set by the engine from the creating actor. */
+  tenantId?: string;
   createdAt: string;
   updatedAt: string;
 }
@@ -127,7 +131,10 @@ export interface Project {
   name: string;
   description?: string;
   ownerId?: string;
-  members?: string[]; // user IDs
+  /** Project membership and roles, used by role-based authorization policies. */
+  members?: ProjectMember[];
+  /** Tenant that owns the project. Set by the engine from the creating actor; never from payloads. */
+  tenantId?: string;
   teamIds?: string[]; // team IDs
   workflowId?: string;
   workflow?: Workflow;
@@ -305,6 +312,21 @@ export interface Actor {
   userId: string;
   username?: string;
   actorType?: AuthorType;
+  /**
+   * Tenant the actor belongs to. When set, the actor only sees projects, workflows and teams
+   * with the same `tenantId`, and everything it creates is stamped with it.
+   */
+  tenantId?: string;
+  /** Workspace-wide roles, e.g. `['admin']`. Interpreted by the authorization policy. */
+  roles?: string[];
+}
+
+/** A user's role on a project. */
+export type ProjectRole = Role;
+
+export interface ProjectMember {
+  userId: string;
+  role: ProjectRole;
 }
 
 export interface CommentReaction {
@@ -462,6 +484,13 @@ export interface CriticalPathPlugin {
 }
 
 export interface CriticalPathConfig {
+  /**
+   * Authorization policy applied to every call made through a `withActor` view (which is how
+   * `@critical-path/server` and the MCP server call the engine). Calls on the base engine are
+   * trusted. Use `createRolePolicy()` for project-membership roles, or supply your own.
+   * When omitted, actors may do anything within their tenant.
+   */
+  authorize?: AuthorizationPolicy;
   store?: 'memory' | 'sqlite' | unknown;
   fileStorage?: FileStorageAdapter;
   plugins?: CriticalPathPlugin[];
@@ -742,3 +771,39 @@ export interface WorkloadDistributionOptions {
   teamSchedules?: Record<string, WorkSchedule>;
 }
 
+// ==========================================
+// Authorization
+// ==========================================
+
+/**
+ * Operations the engine authorizes. Project-scoped actions are checked against a project;
+ * `project.create` and `workspace.manage` (workflows, teams, webhooks) are workspace-level.
+ */
+export type AuthorizationAction =
+  | 'project.read'
+  | 'project.create'
+  | 'project.update'
+  | 'project.delete'
+  | 'project.manage_members'
+  | 'task.create'
+  | 'task.update'
+  | 'task.delete'
+  | 'comment.create'
+  | 'comment.moderate'
+  | 'attachment.create'
+  | 'attachment.delete'
+  | 'time.log'
+  | 'plan.manage'
+  | 'workspace.manage';
+
+export interface AuthorizationRequest {
+  actor: Actor;
+  action: AuthorizationAction;
+  /** The project the action targets, for project-scoped actions. */
+  project?: Project;
+  /** The specific record, when relevant (e.g. the comment being edited). */
+  resource?: { type: 'task' | 'comment' | 'attachment'; ownerId?: string };
+}
+
+export type AuthorizationPolicy = (request: AuthorizationRequest) => boolean | Promise<boolean>;
+

package/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["./src/deliverables.test.ts","./src/index.test.ts","./src/index.ts","./src/status.test.ts","./src/task-state.test.ts","./src/use-case-validation.test.ts","./src/domain/calendar.test.ts","./src/domain/calendar.ts","./src/domain/cpm.test.ts","./src/domain/cpm.ts","./src/domain/custom-fields.ts","./src/domain/ddd.test.ts","./src/domain/entities.ts","./src/domain/errors.ts","./src/domain/events.ts","./src/domain/graph.ts","./src/domain/index.ts","./src/domain/ladder.test.ts","./src/domain/ladder.ts","./src/domain/metrics.test.ts","./src/domain/metrics.ts","./src/domain/task-duration.test.ts","./src/domain/workload.test.ts","./src/domain/workload.ts","./src/engine/actor.test.ts","./src/engine/index.ts","./src/plugins/index.ts","./src/schemas/index.ts","./src/schemas/schemas.test.ts","./src/storage/file-storage.ts","./src/storage/firebase-storage.ts","./src/storage/index.ts","./src/storage/s3.ts","./src/storage/storage.test.ts","./src/store/firebase.test.ts","./src/store/firebase.ts","./src/store/index.ts","./src/store/sqlite.test.ts","./src/store/sqlite.ts","./src/types/index.ts","./src/utils/fractional-index.test.ts","./src/utils/fractional-index.ts","./src/utils/index.ts","./src/utils/key.test.ts","./src/utils/key.ts","./src/utils/mentions.test.ts","./src/utils/mentions.ts","./src/utils/status.ts","./src/utils/workflow.ts"],"version":"5.9.3"}
+{"root":["./src/deliverables.test.ts","./src/index.test.ts","./src/index.ts","./src/status.test.ts","./src/task-state.test.ts","./src/use-case-validation.test.ts","./src/domain/authorization.ts","./src/domain/calendar.test.ts","./src/domain/calendar.ts","./src/domain/cpm.test.ts","./src/domain/cpm.ts","./src/domain/custom-fields.ts","./src/domain/ddd.test.ts","./src/domain/entities.ts","./src/domain/errors.ts","./src/domain/events.ts","./src/domain/graph.ts","./src/domain/index.ts","./src/domain/ladder.test.ts","./src/domain/ladder.ts","./src/domain/metrics.test.ts","./src/domain/metrics.ts","./src/domain/task-duration.test.ts","./src/domain/workload.test.ts","./src/domain/workload.ts","./src/engine/actor.test.ts","./src/engine/authorization.test.ts","./src/engine/index.ts","./src/plugins/index.ts","./src/schemas/index.ts","./src/schemas/schemas.test.ts","./src/storage/file-storage.ts","./src/storage/firebase-storage.ts","./src/storage/index.ts","./src/storage/s3.ts","./src/storage/storage.test.ts","./src/store/firebase.test.ts","./src/store/firebase.ts","./src/store/index.ts","./src/store/sqlite.test.ts","./src/store/sqlite.ts","./src/types/index.ts","./src/utils/fractional-index.test.ts","./src/utils/fractional-index.ts","./src/utils/index.ts","./src/utils/key.test.ts","./src/utils/key.ts","./src/utils/mentions.test.ts","./src/utils/mentions.ts","./src/utils/status.ts","./src/utils/workflow.ts"],"version":"5.9.3"}