bopodev-api 0.1.14 → 0.1.16

package/src/lib/instance-paths.ts

@@ -18,6 +18,11 @@ function normalizePath(raw: string) {
   return resolve(expandHomePrefix(raw.trim()));
 }
 
+type NormalizeAbsolutePathOptions = {
+  requireAbsoluteInput?: boolean;
+  baseDir?: string;
+};
+
 export function resolveBopoHomeDir() {
   const configured = process.env.BOPO_HOME?.trim();
   if (configured) {
@@ -46,20 +51,27 @@ export function resolveBopoInstanceRoot() {
 }
 
 export function resolveProjectWorkspacePath(companyId: string, projectId: string) {
-  assertPathSegment(companyId, "companyId");
-  assertPathSegment(projectId, "projectId");
-  return join(resolveBopoInstanceRoot(), "workspaces", companyId, "projects", projectId);
+  const safeCompanyId = assertPathSegment(companyId, "companyId");
+  const safeProjectId = assertPathSegment(projectId, "projectId");
+  return join(resolveBopoInstanceRoot(), "workspaces", safeCompanyId, "projects", safeProjectId);
 }
 
 export function resolveCompanyProjectsWorkspacePath(companyId: string) {
-  assertPathSegment(companyId, "companyId");
-  return join(resolveBopoInstanceRoot(), "workspaces", companyId);
+  const safeCompanyId = assertPathSegment(companyId, "companyId");
+  return join(resolveBopoInstanceRoot(), "workspaces", safeCompanyId);
 }
 
 export function resolveAgentFallbackWorkspacePath(companyId: string, agentId: string) {
-  assertPathSegment(companyId, "companyId");
-  assertPathSegment(agentId, "agentId");
-  return join(resolveBopoInstanceRoot(), "workspaces", companyId, "agents", agentId);
+  const safeCompanyId = assertPathSegment(companyId, "companyId");
+  const safeAgentId = assertPathSegment(agentId, "agentId");
+  return join(resolveBopoInstanceRoot(), "workspaces", safeCompanyId, "agents", safeAgentId);
+}
+
+export function resolveAgentProjectWorktreeRootPath(companyId: string, agentId: string, projectId: string) {
+  const safeCompanyId = assertPathSegment(companyId, "companyId");
+  const safeAgentId = assertPathSegment(agentId, "agentId");
+  const safeProjectId = assertPathSegment(projectId, "projectId");
+  return join(resolveBopoInstanceRoot(), "workspaces", safeCompanyId, "agents", safeAgentId, "worktrees", safeProjectId);
 }
 
 export function resolveAgentMemoryRootPath(companyId: string, agentId: string) {
@@ -78,8 +90,19 @@ export function resolveStorageRoot() {
   return join(resolveBopoInstanceRoot(), "data", "storage");
 }
 
-export function normalizeAbsolutePath(value: string) {
-  return normalizePath(value);
+export function normalizeAbsolutePath(value: string, options?: NormalizeAbsolutePathOptions) {
+  const trimmed = value.trim();
+  const expanded = expandHomePrefix(trimmed);
+  if (options?.requireAbsoluteInput && !isAbsolute(expanded)) {
+    throw new Error(`Expected absolute path input, received '${value}'.`);
+  }
+  if (isAbsolute(expanded)) {
+    return resolve(expanded);
+  }
+  if (options?.baseDir) {
+    return resolve(options.baseDir, expanded);
+  }
+  return resolve(expanded);
 }
 
 export function isInsidePath(parent: string, child: string) {
@@ -92,9 +115,51 @@ export function isInsidePath(parent: string, child: string) {
   return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
 }
 
+export function resolveWorkspaceRootPath() {
+  return join(resolveBopoInstanceRoot(), "workspaces");
+}
+
+export function resolveCompanyWorkspaceRootPath(companyId: string) {
+  return resolveCompanyProjectsWorkspacePath(companyId);
+}
+
+export function assertPathInsidePath(parent: string, candidate: string, label = "path") {
+  const normalizedParent = normalizeAbsolutePath(parent, { requireAbsoluteInput: true });
+  const normalizedCandidate = normalizeAbsolutePath(candidate, { requireAbsoluteInput: true });
+  if (!isInsidePath(normalizedParent, normalizedCandidate)) {
+    throw new Error(`Invalid ${label} '${candidate}': must be inside '${normalizedParent}'.`);
+  }
+  return normalizedCandidate;
+}
+
+export function assertPathInsideWorkspaceRoot(candidate: string, label = "path") {
+  return assertPathInsidePath(resolveWorkspaceRootPath(), candidate, label);
+}
+
+export function assertPathInsideCompanyWorkspaceRoot(companyId: string, candidate: string, label = "path") {
+  return assertPathInsidePath(resolveCompanyWorkspaceRootPath(companyId), candidate, label);
+}
+
+export function normalizeCompanyWorkspacePath(
+  companyId: string,
+  value: string,
+  options?: { requireAbsoluteInput?: boolean }
+) {
+  const companyWorkspaceRoot = resolveCompanyWorkspaceRootPath(companyId);
+  const normalized = normalizeAbsolutePath(value, {
+    requireAbsoluteInput: options?.requireAbsoluteInput ?? false,
+    baseDir: companyWorkspaceRoot
+  });
+  return assertPathInsideCompanyWorkspaceRoot(companyId, normalized, "workspace path");
+}
+
 function assertPathSegment(value: string, label: string) {
   const trimmed = value.trim();
+  if (trimmed !== value) {
+    throw new Error(`Invalid ${label} for workspace path '${value}'.`);
+  }
   if (!SAFE_PATH_SEGMENT_RE.test(trimmed)) {
     throw new Error(`Invalid ${label} for workspace path '${value}'.`);
   }
+  return trimmed;
 }

package/src/lib/workspace-policy.ts

@@ -1,8 +1,10 @@
 import { and, eq, inArray } from "drizzle-orm";
 import type { BopoDb } from "bopodev-db";
-import { projects } from "bopodev-db";
+import { projectWorkspaces, projects } from "bopodev-db";
 import {
+  assertPathInsideCompanyWorkspaceRoot,
   isInsidePath,
+  normalizeCompanyWorkspacePath,
   normalizeAbsolutePath,
   resolveAgentFallbackWorkspacePath,
   resolveAgentMemoryRootPath,
@@ -13,6 +15,24 @@ export function hasText(value: string | null | undefined) {
   return Boolean(value && value.trim().length > 0);
 }
 
+export type ExecutionWorkspaceMode = "project_primary" | "isolated" | "agent_default";
+export type ExecutionWorkspaceStrategyType = "git_worktree";
+export interface ProjectExecutionWorkspacePolicy {
+  mode?: ExecutionWorkspaceMode;
+  strategy?: {
+    type?: ExecutionWorkspaceStrategyType;
+    rootDir?: string | null;
+    branchPrefix?: string | null;
+  } | null;
+  credentials?: {
+    mode?: "host" | "env_token";
+    tokenEnvVar?: string | null;
+    username?: string | null;
+  } | null;
+  allowRemotes?: string[] | null;
+  allowBranchPrefixes?: string[] | null;
+}
+
 export function parseRuntimeCwd(stateBlob: string | null | undefined) {
   if (!stateBlob) {
     return null;
@@ -28,18 +48,18 @@ export function parseRuntimeCwd(stateBlob: string | null | undefined) {
 
 export async function inferSingleWorkspaceLocalPath(db: BopoDb, companyId: string) {
   const rows = await db
-    .select({ workspaceLocalPath: projects.workspaceLocalPath })
-    .from(projects)
-    .where(eq(projects.companyId, companyId));
+    .select({ cwd: projectWorkspaces.cwd })
+    .from(projectWorkspaces)
+    .where(and(eq(projectWorkspaces.companyId, companyId), eq(projectWorkspaces.isPrimary, true)));
   const paths = Array.from(
     new Set(
       rows
-        .map((row) => row.workspaceLocalPath?.trim() ?? "")
+        .map((row) => row.cwd?.trim() ?? "")
         .filter((value) => value.length > 0)
     )
   );
   const singlePath = paths.length === 1 ? paths[0] : null;
-  return singlePath ? normalizeAbsolutePath(singlePath) : null;
+  return singlePath ? normalizeCompanyWorkspacePath(companyId, singlePath) : null;
 }
 
 export async function resolveDefaultRuntimeCwdForCompany(db: BopoDb, companyId: string) {
@@ -51,14 +71,74 @@ export async function resolveDefaultRuntimeCwdForCompany(db: BopoDb, companyId:
 }
 
 export async function getProjectWorkspaceMap(db: BopoDb, companyId: string, projectIds: string[]) {
+  const context = await getProjectWorkspaceContextMap(db, companyId, projectIds);
+  return new Map(Array.from(context.entries()).map(([projectId, value]) => [projectId, value.cwd]));
+}
+
+export async function getProjectWorkspaceContextMap(db: BopoDb, companyId: string, projectIds: string[]) {
   if (projectIds.length === 0) {
-    return new Map<string, string | null>();
+    return new Map<
+      string,
+      {
+        workspaceId: string | null;
+        workspaceName: string | null;
+        cwd: string | null;
+        repoUrl: string | null;
+        repoRef: string | null;
+        policy: ProjectExecutionWorkspacePolicy | null;
+      }
+    >();
   }
-  const rows = await db
-    .select({ id: projects.id, workspaceLocalPath: projects.workspaceLocalPath })
+  const workspaceRows = await db
+    .select({
+      id: projectWorkspaces.id,
+      projectId: projectWorkspaces.projectId,
+      name: projectWorkspaces.name,
+      cwd: projectWorkspaces.cwd,
+      repoUrl: projectWorkspaces.repoUrl,
+      repoRef: projectWorkspaces.repoRef
+    })
+    .from(projectWorkspaces)
+    .where(
+      and(
+        eq(projectWorkspaces.companyId, companyId),
+        inArray(projectWorkspaces.projectId, projectIds),
+        eq(projectWorkspaces.isPrimary, true)
+      )
+    );
+  const projectRows = await db
+    .select({ id: projects.id, executionWorkspacePolicy: projects.executionWorkspacePolicy })
     .from(projects)
     .where(and(eq(projects.companyId, companyId), inArray(projects.id, projectIds)));
-  return new Map(rows.map((row) => [row.id, row.workspaceLocalPath ? normalizeAbsolutePath(row.workspaceLocalPath) : null]));
+
+  const workspaceMap = new Map(
+    workspaceRows.map((row) => [row.projectId, row.cwd ? normalizeCompanyWorkspacePath(companyId, row.cwd) : null])
+  );
+  const workspaceByProject = new Map(workspaceRows.map((row) => [row.projectId, row]));
+  const policyMap = new Map(projectRows.map((row) => [row.id, parseProjectExecutionWorkspacePolicy(row.executionWorkspacePolicy)]));
+  const result = new Map<
+    string,
+    {
+      workspaceId: string | null;
+      workspaceName: string | null;
+      cwd: string | null;
+      repoUrl: string | null;
+      repoRef: string | null;
+      policy: ProjectExecutionWorkspacePolicy | null;
+    }
+  >();
+  for (const projectId of projectIds) {
+    const workspace = workspaceByProject.get(projectId);
+    result.set(projectId, {
+      workspaceId: workspace?.id ?? null,
+      workspaceName: workspace?.name ?? null,
+      cwd: workspaceMap.get(projectId) ?? null,
+      repoUrl: workspace?.repoUrl?.trim() ? workspace.repoUrl.trim() : null,
+      repoRef: workspace?.repoRef?.trim() ? workspace.repoRef.trim() : null,
+      policy: policyMap.get(projectId) ?? null
+    });
+  }
+  return result;
 }
 
 export function ensureRuntimeInsideWorkspace(projectWorkspacePath: string, runtimeCwd: string) {
@@ -78,3 +158,66 @@ export function resolveAgentFallbackWorkspace(companyId: string, agentId: string
 export function resolveAgentMemoryRoot(companyId: string, agentId: string) {
   return resolveAgentMemoryRootPath(companyId, agentId);
 }
+
+export function parseProjectExecutionWorkspacePolicy(
+  value: string | Record<string, unknown> | null | undefined
+): ProjectExecutionWorkspacePolicy | null {
+  if (!value) {
+    return null;
+  }
+  const parsedValue =
+    typeof value === "string"
+      ? (() => {
+          try {
+            return JSON.parse(value) as Record<string, unknown>;
+          } catch {
+            return null;
+          }
+        })()
+      : value;
+  if (!parsedValue || typeof parsedValue !== "object") {
+    return null;
+  }
+  const mode = parsedValue.mode;
+  const strategy = parsedValue.strategy as Record<string, unknown> | undefined;
+  const normalizedMode: ExecutionWorkspaceMode | undefined =
+    mode === "project_primary" || mode === "isolated" || mode === "agent_default" ? mode : undefined;
+  const normalizedStrategy =
+    strategy && typeof strategy === "object"
+      ? {
+          type: strategy.type === "git_worktree" ? ("git_worktree" as const) : undefined,
+          rootDir: typeof strategy.rootDir === "string" ? strategy.rootDir : null,
+          branchPrefix: typeof strategy.branchPrefix === "string" ? strategy.branchPrefix : null
+        }
+      : null;
+  const credentials = parsedValue.credentials as Record<string, unknown> | undefined;
+  const normalizedCredentials =
+    credentials && typeof credentials === "object"
+      ? {
+          mode:
+            credentials.mode === "host" || credentials.mode === "env_token"
+              ? (credentials.mode as "host" | "env_token")
+              : undefined,
+          tokenEnvVar: typeof credentials.tokenEnvVar === "string" ? credentials.tokenEnvVar : null,
+          username: typeof credentials.username === "string" ? credentials.username : null
+        }
+      : null;
+  const allowRemotes = Array.isArray(parsedValue.allowRemotes)
+    ? parsedValue.allowRemotes.map((entry) => String(entry).trim()).filter((entry) => entry.length > 0)
+    : null;
+  const allowBranchPrefixes = Array.isArray(parsedValue.allowBranchPrefixes)
+    ? parsedValue.allowBranchPrefixes.map((entry) => String(entry).trim()).filter((entry) => entry.length > 0)
+    : null;
+  return {
+    mode: normalizedMode,
+    strategy: normalizedStrategy,
+    credentials: normalizedCredentials,
+    allowRemotes,
+    allowBranchPrefixes
+  };
+}
+
+export function assertRuntimeCwdForCompany(companyId: string, runtimeCwd: string, label = "runtimeCwd") {
+  const normalized = normalizeAbsolutePath(runtimeCwd, { requireAbsoluteInput: true });
+  return assertPathInsideCompanyWorkspaceRoot(companyId, normalized, label);
+}

package/src/middleware/request-actor.ts

@@ -1,6 +1,8 @@
 import type { NextFunction, Request, Response } from "express";
 import { RequestActorHeadersSchema } from "bopodev-contracts";
 import { sendError } from "../http";
+import { verifyActorToken } from "../security/actor-token";
+import { isAuthenticatedMode, resolveDeploymentMode } from "../security/deployment-mode";
 
 export type RequestActor = {
   type: "board" | "member" | "agent";
@@ -20,6 +22,22 @@ declare global {
 }
 
 export function attachRequestActor(req: Request, res: Response, next: NextFunction) {
+  const deploymentMode = resolveDeploymentMode();
+  const tokenSecret = process.env.BOPO_AUTH_TOKEN_SECRET?.trim() || "";
+  const tokenIdentity = tokenSecret
+    ? verifyActorToken(readBearerToken(req.header("authorization")) ?? req.header("x-bopo-actor-token"), tokenSecret)
+    : null;
+  if (tokenIdentity) {
+    req.actor = {
+      type: tokenIdentity.type,
+      id: tokenIdentity.id,
+      companyIds: tokenIdentity.companyIds,
+      permissions: tokenIdentity.permissions
+    };
+    next();
+    return;
+  }
+
   const actorHeadersResult = RequestActorHeadersSchema.safeParse({
     "x-actor-type": req.header("x-actor-type")?.trim().toLowerCase(),
     "x-actor-id": req.header("x-actor-id")?.trim(),
@@ -39,9 +57,44 @@ export function attachRequestActor(req: Request, res: Response, next: NextFuncti
   const companyIds = parseCommaList(actorHeaders["x-actor-companies"]);
   const permissions = parseCommaList(actorHeaders["x-actor-permissions"]) ?? [];
   const hasActorHeaders = Boolean(
-    actorHeaders["x-actor-type"] || actorHeaders["x-actor-id"] || companyIds || permissions.length > 0
+    actorHeaders["x-actor-type"] ||
+      actorHeaders["x-actor-id"] ||
+      (companyIds && companyIds.length > 0) ||
+      permissions.length > 0
   );
-  const allowLocalBoardFallback = process.env.NODE_ENV !== "production" && process.env.BOPO_ALLOW_LOCAL_BOARD_FALLBACK !== "0";
+  const allowLocalBoardFallback =
+    deploymentMode === "local" && process.env.NODE_ENV !== "production" && process.env.BOPO_ALLOW_LOCAL_BOARD_FALLBACK !== "0";
+  const trustActorHeaders = deploymentMode === "local" || process.env.BOPO_TRUST_ACTOR_HEADERS === "1";
+  const bootstrapSecret = process.env.BOPO_AUTH_BOOTSTRAP_SECRET?.trim();
+  const bootstrapHeader = req.header("x-bopo-bootstrap-secret")?.trim();
+  const allowBootstrapTokenIssue =
+    req.method === "POST" &&
+    req.path === "/auth/actor-token" &&
+    Boolean(bootstrapSecret && bootstrapHeader && bootstrapSecret === bootstrapHeader);
+  if (isAuthenticatedMode(deploymentMode) && !hasActorHeaders && !tokenIdentity) {
+    if (allowBootstrapTokenIssue) {
+      req.actor = {
+        type: "board",
+        id: "bootstrap-secret",
+        companyIds: null,
+        permissions: []
+      };
+      next();
+      return;
+    }
+    return sendError(
+      res,
+      "Missing actor identity. Provide Authorization Bearer actor token or trusted x-actor-* headers.",
+      401
+    );
+  }
+  if (isAuthenticatedMode(deploymentMode) && hasActorHeaders && !trustActorHeaders) {
+    return sendError(
+      res,
+      "x-actor-* headers are disabled in authenticated mode. Set BOPO_TRUST_ACTOR_HEADERS=1 only behind a trusted proxy.",
+      401
+    );
+  }
   const actorType = hasActorHeaders
     ? actorHeaders["x-actor-type"] ?? "member"
     : allowLocalBoardFallback
@@ -62,6 +115,18 @@ export function attachRequestActor(req: Request, res: Response, next: NextFuncti
   next();
 }
 
+function readBearerToken(value: string | undefined) {
+  const trimmed = value?.trim();
+  if (!trimmed) {
+    return null;
+  }
+  const lower = trimmed.toLowerCase();
+  if (!lower.startsWith("bearer ")) {
+    return null;
+  }
+  return trimmed.slice("bearer ".length).trim() || null;
+}
+
 export function requirePermission(permission: string) {
   return (req: Request, res: Response, next: NextFunction) => {
     if (!hasPermission(req, permission)) {

package/src/realtime/hub.ts

@@ -5,6 +5,8 @@ import {
   type RealtimeMessage
 } from "bopodev-contracts";
 import { WebSocket, WebSocketServer } from "ws";
+import { verifyActorToken } from "../security/actor-token";
+import { isAuthenticatedMode, resolveDeploymentMode } from "../security/deployment-mode";
 
 type RealtimeEventMessage = Extract<RealtimeMessage, { kind: "event" }>;
 type RealtimeBootstrapLoader = (companyId: string) => Promise<RealtimeEventMessage>;
@@ -25,7 +27,7 @@ export function attachRealtimeHub(
 
   wss.on("connection", async (socket, request) => {
     const subscription = getSubscription(request.url);
-    if (!subscription || !canSubscribeToCompany(request.headers, subscription.companyId)) {
+    if (!subscription || !canSubscribeToCompany(request.url, request.headers, subscription.companyId)) {
       socket.close(1008, "Invalid realtime subscription");
       return;
     }
@@ -132,13 +134,31 @@ function getSubscription(requestUrl: string | undefined) {
 }
 
 function canSubscribeToCompany(
+  requestUrl: string | undefined,
   headers: Record<string, string | string[] | undefined>,
   companyId: string
 ) {
+  const deploymentMode = resolveDeploymentMode();
+  const tokenSecret = process.env.BOPO_AUTH_TOKEN_SECRET?.trim() || "";
+  const tokenIdentity = tokenSecret ? verifyActorToken(readRealtimeTokenFromUrl(requestUrl), tokenSecret) : null;
+  if (tokenIdentity) {
+    if (tokenIdentity.type === "board") {
+      return true;
+    }
+    return tokenIdentity.companyIds?.includes(companyId) ?? false;
+  }
   const actorType = readHeader(headers, "x-actor-type")?.toLowerCase();
   const actorCompanies = parseCommaList(readHeader(headers, "x-actor-companies"));
   const hasActorHeaders = Boolean(actorType || actorCompanies.length > 0);
-  const allowLocalBoardFallback = process.env.NODE_ENV !== "production" && process.env.BOPO_ALLOW_LOCAL_BOARD_FALLBACK !== "0";
+  const allowLocalBoardFallback =
+    deploymentMode === "local" && process.env.NODE_ENV !== "production" && process.env.BOPO_ALLOW_LOCAL_BOARD_FALLBACK !== "0";
+  const trustActorHeaders = deploymentMode === "local" || process.env.BOPO_TRUST_ACTOR_HEADERS === "1";
+  if (isAuthenticatedMode(deploymentMode) && !hasActorHeaders) {
+    return false;
+  }
+  if (isAuthenticatedMode(deploymentMode) && hasActorHeaders && !trustActorHeaders) {
+    return false;
+  }
 
   if (!hasActorHeaders) {
     return allowLocalBoardFallback;
@@ -149,6 +169,15 @@ function canSubscribeToCompany(
   return actorCompanies.includes(companyId);
 }
 
+function readRealtimeTokenFromUrl(requestUrl: string | undefined) {
+  if (!requestUrl) {
+    return null;
+  }
+  const url = new URL(requestUrl, "http://localhost");
+  const token = url.searchParams.get("authToken")?.trim();
+  return token && token.length > 0 ? token : null;
+}
+
 function readHeader(headers: Record<string, string | string[] | undefined>, name: string) {
   const value = headers[name];
   if (Array.isArray(value)) {