corporateai 0.0.1

package/server/src/startup-banner.ts

@@ -0,0 +1,176 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolvePaperclipConfigPath, resolvePaperclipEnvPath } from "./paths.js";
+import type { DeploymentExposure, DeploymentMode } from "@corporateai/shared";
+
+import { parse as parseEnvFileContents } from "dotenv";
+
+type UiMode = "none" | "static" | "vite-dev";
+
+type ExternalPostgresInfo = {
+  mode: "external-postgres";
+  connectionString: string;
+};
+
+type EmbeddedPostgresInfo = {
+  mode: "embedded-postgres";
+  dataDir: string;
+  port: number;
+};
+
+type StartupBannerOptions = {
+  host: string;
+  deploymentMode: DeploymentMode;
+  deploymentExposure: DeploymentExposure;
+  authReady: boolean;
+  requestedPort: number;
+  listenPort: number;
+  uiMode: UiMode;
+  db: ExternalPostgresInfo | EmbeddedPostgresInfo;
+  migrationSummary: string;
+  heartbeatSchedulerEnabled: boolean;
+  heartbeatSchedulerIntervalMs: number;
+  databaseBackupEnabled: boolean;
+  databaseBackupIntervalMinutes: number;
+  databaseBackupRetentionDays: number;
+  databaseBackupDir: string;
+};
+
+const ansi = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  cyan: "\x1b[36m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  magenta: "\x1b[35m",
+  blue: "\x1b[34m",
+};
+
+function color(text: string, c: keyof typeof ansi): string {
+  return `${ansi[c]}${text}${ansi.reset}`;
+}
+
+function row(label: string, value: string): string {
+  return `${color(label.padEnd(16), "dim")} ${value}`;
+}
+
+function redactConnectionString(raw: string): string {
+  try {
+    const u = new URL(raw);
+    const user = u.username || "user";
+    const auth = `${user}:***@`;
+    return `${u.protocol}//${auth}${u.host}${u.pathname}`;
+  } catch {
+    return "<invalid DATABASE_URL>";
+  }
+}
+
+function resolveAgentJwtSecretStatus(
+  envFilePath: string,
+): {
+  status: "pass" | "warn";
+  message: string;
+} {
+  const envValue = process.env.PAPERCLIP_AGENT_JWT_SECRET?.trim();
+  if (envValue) {
+    return {
+      status: "pass",
+      message: "set",
+    };
+  }
+
+  if (existsSync(envFilePath)) {
+    const parsed = parseEnvFileContents(readFileSync(envFilePath, "utf-8"));
+    const fileValue = typeof parsed.PAPERCLIP_AGENT_JWT_SECRET === "string" ? parsed.PAPERCLIP_AGENT_JWT_SECRET.trim() : "";
+    if (fileValue) {
+      return {
+        status: "warn",
+        message: `found in ${envFilePath} but not loaded`,
+      };
+    }
+  }
+
+  return {
+    status: "warn",
+    message: "missing (run `pnpm corporateai onboard`)",
+  };
+}
+
+export function printStartupBanner(opts: StartupBannerOptions): void {
+  const baseHost = opts.host === "0.0.0.0" ? "localhost" : opts.host;
+  const baseUrl = `http://${baseHost}:${opts.listenPort}`;
+  const apiUrl = `${baseUrl}/api`;
+  const uiUrl = opts.uiMode === "none" ? "disabled" : baseUrl;
+  const configPath = resolvePaperclipConfigPath();
+  const envFilePath = resolvePaperclipEnvPath();
+  const agentJwtSecret = resolveAgentJwtSecretStatus(envFilePath);
+
+  const dbMode =
+    opts.db.mode === "embedded-postgres"
+      ? color("embedded-postgres", "green")
+      : color("external-postgres", "yellow");
+  const uiMode =
+    opts.uiMode === "vite-dev"
+      ? color("vite-dev-middleware", "cyan")
+      : opts.uiMode === "static"
+        ? color("static-ui", "magenta")
+        : color("headless-api", "yellow");
+
+  const portValue =
+    opts.requestedPort === opts.listenPort
+      ? `${opts.listenPort}`
+      : `${opts.listenPort} ${color(`(requested ${opts.requestedPort})`, "dim")}`;
+
+  const dbDetails =
+    opts.db.mode === "embedded-postgres"
+      ? `${opts.db.dataDir} ${color(`(pg:${opts.db.port})`, "dim")}`
+      : redactConnectionString(opts.db.connectionString);
+
+  const heartbeat = opts.heartbeatSchedulerEnabled
+    ? `enabled ${color(`(${opts.heartbeatSchedulerIntervalMs}ms)`, "dim")}`
+    : color("disabled", "yellow");
+  const dbBackup = opts.databaseBackupEnabled
+    ? `enabled ${color(`(every ${opts.databaseBackupIntervalMinutes}m, keep ${opts.databaseBackupRetentionDays}d)`, "dim")}`
+    : color("disabled", "yellow");
+
+  const art = [
+    color("██████╗  █████╗ ██████╗ ███████╗██████╗  ██████╗██╗     ██╗██████╗ ", "cyan"),
+    color("██╔══██╗██╔══██╗██╔══██╗██╔════╝██╔══██╗██╔════╝██║     ██║██╔══██╗", "cyan"),
+    color("██████╔╝███████║██████╔╝█████╗  ██████╔╝██║     ██║     ██║██████╔╝", "cyan"),
+    color("██╔═══╝ ██╔══██║██╔═══╝ ██╔══╝  ██╔══██╗██║     ██║     ██║██╔═══╝ ", "cyan"),
+    color("██║     ██║  ██║██║     ███████╗██║  ██║╚██████╗███████╗██║██║     ", "cyan"),
+    color("╚═╝     ╚═╝  ╚═╝╚═╝     ╚══════╝╚═╝  ╚═╝ ╚═════╝╚══════╝╚═╝╚═╝     ", "cyan"),
+  ];
+
+  const lines = [
+    "",
+    ...art,
+    color("  ───────────────────────────────────────────────────────", "blue"),
+    row("Mode", `${dbMode}  |  ${uiMode}`),
+    row("Deploy", `${opts.deploymentMode} (${opts.deploymentExposure})`),
+    row("Auth", opts.authReady ? color("ready", "green") : color("not-ready", "yellow")),
+    row("Server", portValue),
+    row("API", `${apiUrl} ${color(`(health: ${apiUrl}/health)`, "dim")}`),
+    row("UI", uiUrl),
+    row("Database", dbDetails),
+    row("Migrations", opts.migrationSummary),
+    row(
+      "Agent JWT",
+      agentJwtSecret.status === "pass"
+        ? color(agentJwtSecret.message, "green")
+        : color(agentJwtSecret.message, "yellow"),
+    ),
+    row("Heartbeat", heartbeat),
+    row("DB Backup", dbBackup),
+    row("Backup Dir", opts.databaseBackupDir),
+    row("Config", configPath),
+    agentJwtSecret.status === "warn"
+      ? color("  ───────────────────────────────────────────────────────", "yellow")
+      : null,
+    color("  ───────────────────────────────────────────────────────", "blue"),
+    "",
+  ];
+
+  console.log(lines.filter((line): line is string => line !== null).join("\n"));
+}
+

package/server/src/storage/index.ts

@@ -0,0 +1,35 @@
+import { loadConfig, type Config } from "../config.js";
+import { createStorageProviderFromConfig } from "./provider-registry.js";
+import { createStorageService } from "./service.js";
+import type { StorageService } from "./types.js";
+
+let cachedStorageService: StorageService | null = null;
+let cachedSignature: string | null = null;
+
+function signatureForConfig(config: Config): string {
+  return JSON.stringify({
+    provider: config.storageProvider,
+    localDisk: config.storageLocalDiskBaseDir,
+    s3Bucket: config.storageS3Bucket,
+    s3Region: config.storageS3Region,
+    s3Endpoint: config.storageS3Endpoint,
+    s3Prefix: config.storageS3Prefix,
+    s3ForcePathStyle: config.storageS3ForcePathStyle,
+  });
+}
+
+export function createStorageServiceFromConfig(config: Config): StorageService {
+  return createStorageService(createStorageProviderFromConfig(config));
+}
+
+export function getStorageService(): StorageService {
+  const config = loadConfig();
+  const signature = signatureForConfig(config);
+  if (!cachedStorageService || cachedSignature !== signature) {
+    cachedStorageService = createStorageServiceFromConfig(config);
+    cachedSignature = signature;
+  }
+  return cachedStorageService;
+}
+
+export type { StorageService, PutFileResult } from "./types.js";

package/server/src/storage/local-disk-provider.ts

@@ -0,0 +1,89 @@
+import { createReadStream, promises as fs } from "node:fs";
+import path from "node:path";
+import type { StorageProvider, GetObjectResult, HeadObjectResult } from "./types.js";
+import { notFound, badRequest } from "../errors.js";
+
+function normalizeObjectKey(objectKey: string): string {
+  const normalized = objectKey.replace(/\\/g, "/").trim();
+  if (!normalized || normalized.startsWith("/")) {
+    throw badRequest("Invalid object key");
+  }
+
+  const parts = normalized.split("/").filter((part) => part.length > 0);
+  if (parts.length === 0 || parts.some((part) => part === "." || part === "..")) {
+    throw badRequest("Invalid object key");
+  }
+
+  return parts.join("/");
+}
+
+function resolveWithin(baseDir: string, objectKey: string): string {
+  const normalizedKey = normalizeObjectKey(objectKey);
+  const resolved = path.resolve(baseDir, normalizedKey);
+  const base = path.resolve(baseDir);
+  if (resolved !== base && !resolved.startsWith(base + path.sep)) {
+    throw badRequest("Invalid object key path");
+  }
+  return resolved;
+}
+
+async function statOrNull(filePath: string) {
+  try {
+    return await fs.stat(filePath);
+  } catch {
+    return null;
+  }
+}
+
+export function createLocalDiskStorageProvider(baseDir: string): StorageProvider {
+  const root = path.resolve(baseDir);
+
+  return {
+    id: "local_disk",
+
+    async putObject(input) {
+      const targetPath = resolveWithin(root, input.objectKey);
+      const dir = path.dirname(targetPath);
+      await fs.mkdir(dir, { recursive: true });
+
+      const tempPath = `${targetPath}.tmp-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+      await fs.writeFile(tempPath, input.body);
+      await fs.rename(tempPath, targetPath);
+    },
+
+    async getObject(input): Promise<GetObjectResult> {
+      const filePath = resolveWithin(root, input.objectKey);
+      const stat = await statOrNull(filePath);
+      if (!stat || !stat.isFile()) {
+        throw notFound("Object not found");
+      }
+      return {
+        stream: createReadStream(filePath),
+        contentLength: stat.size,
+        lastModified: stat.mtime,
+      };
+    },
+
+    async headObject(input): Promise<HeadObjectResult> {
+      const filePath = resolveWithin(root, input.objectKey);
+      const stat = await statOrNull(filePath);
+      if (!stat || !stat.isFile()) {
+        return { exists: false };
+      }
+      return {
+        exists: true,
+        contentLength: stat.size,
+        lastModified: stat.mtime,
+      };
+    },
+
+    async deleteObject(input): Promise<void> {
+      const filePath = resolveWithin(root, input.objectKey);
+      try {
+        await fs.unlink(filePath);
+      } catch {
+        // idempotent delete
+      }
+    },
+  };
+}

package/server/src/storage/provider-registry.ts

@@ -0,0 +1,18 @@
+import type { Config } from "../config.js";
+import type { StorageProvider } from "./types.js";
+import { createLocalDiskStorageProvider } from "./local-disk-provider.js";
+import { createS3StorageProvider } from "./s3-provider.js";
+
+export function createStorageProviderFromConfig(config: Config): StorageProvider {
+  if (config.storageProvider === "local_disk") {
+    return createLocalDiskStorageProvider(config.storageLocalDiskBaseDir);
+  }
+
+  return createS3StorageProvider({
+    bucket: config.storageS3Bucket,
+    region: config.storageS3Region,
+    endpoint: config.storageS3Endpoint,
+    prefix: config.storageS3Prefix,
+    forcePathStyle: config.storageS3ForcePathStyle,
+  });
+}

package/server/src/storage/s3-provider.ts

@@ -0,0 +1,153 @@
+import {
+  S3Client,
+  DeleteObjectCommand,
+  GetObjectCommand,
+  HeadObjectCommand,
+  PutObjectCommand,
+} from "@aws-sdk/client-s3";
+import { Readable } from "node:stream";
+import type { StorageProvider, GetObjectResult, HeadObjectResult } from "./types.js";
+import { notFound, unprocessable } from "../errors.js";
+
+interface S3ProviderConfig {
+  bucket: string;
+  region: string;
+  endpoint?: string;
+  prefix?: string;
+  forcePathStyle?: boolean;
+}
+
+function normalizePrefix(prefix: string | undefined): string {
+  if (!prefix) return "";
+  return prefix
+    .trim()
+    .replace(/^\/+/, "")
+    .replace(/\/+$/, "");
+}
+
+function buildKey(prefix: string, objectKey: string): string {
+  if (!prefix) return objectKey;
+  return `${prefix}/${objectKey}`;
+}
+
+async function toReadableStream(body: unknown): Promise<Readable> {
+  if (!body) throw notFound("Object not found");
+  if (body instanceof Readable) return body;
+
+  const candidate = body as {
+    transformToWebStream?: () => ReadableStream<Uint8Array>;
+    arrayBuffer?: () => Promise<ArrayBuffer>;
+  };
+
+  if (typeof candidate.transformToWebStream === "function") {
+    const webStream = candidate.transformToWebStream();
+    const reader = webStream.getReader();
+    return Readable.from((async function* () {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        if (value) yield value;
+      }
+    })());
+  }
+
+  if (typeof candidate.arrayBuffer === "function") {
+    const buffer = Buffer.from(await candidate.arrayBuffer());
+    return Readable.from(buffer);
+  }
+
+  throw unprocessable("Unsupported S3 body stream type");
+}
+
+function toDate(value: Date | undefined): Date | undefined {
+  return value instanceof Date ? value : undefined;
+}
+
+export function createS3StorageProvider(config: S3ProviderConfig): StorageProvider {
+  const bucket = config.bucket.trim();
+  const region = config.region.trim();
+  if (!bucket) throw unprocessable("S3 storage bucket is required");
+  if (!region) throw unprocessable("S3 storage region is required");
+
+  const prefix = normalizePrefix(config.prefix);
+  const client = new S3Client({
+    region,
+    endpoint: config.endpoint,
+    forcePathStyle: Boolean(config.forcePathStyle),
+  });
+
+  return {
+    id: "s3",
+
+    async putObject(input) {
+      const key = buildKey(prefix, input.objectKey);
+      await client.send(
+        new PutObjectCommand({
+          Bucket: bucket,
+          Key: key,
+          Body: input.body,
+          ContentType: input.contentType,
+          ContentLength: input.contentLength,
+        }),
+      );
+    },
+
+    async getObject(input): Promise<GetObjectResult> {
+      const key = buildKey(prefix, input.objectKey);
+      try {
+        const output = await client.send(
+          new GetObjectCommand({
+            Bucket: bucket,
+            Key: key,
+          }),
+        );
+
+        return {
+          stream: await toReadableStream(output.Body),
+          contentType: output.ContentType,
+          contentLength: output.ContentLength,
+          etag: output.ETag,
+          lastModified: toDate(output.LastModified),
+        };
+      } catch (err) {
+        const code = (err as { name?: string }).name;
+        if (code === "NoSuchKey" || code === "NotFound") throw notFound("Object not found");
+        throw err;
+      }
+    },
+
+    async headObject(input): Promise<HeadObjectResult> {
+      const key = buildKey(prefix, input.objectKey);
+      try {
+        const output = await client.send(
+          new HeadObjectCommand({
+            Bucket: bucket,
+            Key: key,
+          }),
+        );
+
+        return {
+          exists: true,
+          contentType: output.ContentType,
+          contentLength: output.ContentLength,
+          etag: output.ETag,
+          lastModified: toDate(output.LastModified),
+        };
+      } catch (err) {
+        const code = (err as { name?: string }).name;
+        if (code === "NoSuchKey" || code === "NotFound") return { exists: false };
+        throw err;
+      }
+    },
+
+    async deleteObject(input): Promise<void> {
+      const key = buildKey(prefix, input.objectKey);
+      await client.send(
+        new DeleteObjectCommand({
+          Bucket: bucket,
+          Key: key,
+        }),
+      );
+    },
+  };
+}

package/server/src/storage/service.ts

@@ -0,0 +1,131 @@
+import { createHash, randomUUID } from "node:crypto";
+import path from "node:path";
+import type { StorageService, StorageProvider, PutFileInput, PutFileResult } from "./types.js";
+import { badRequest, forbidden, unprocessable } from "../errors.js";
+
+const MAX_SEGMENT_LENGTH = 120;
+
+function sanitizeSegment(value: string): string {
+  const cleaned = value
+    .trim()
+    .replace(/[^a-zA-Z0-9._-]+/g, "_")
+    .replace(/_{2,}/g, "_")
+    .replace(/^_+|_+$/g, "");
+  if (!cleaned) return "file";
+  return cleaned.slice(0, MAX_SEGMENT_LENGTH);
+}
+
+function normalizeNamespace(namespace: string): string {
+  const normalized = namespace
+    .split("/")
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0)
+    .map((entry) => sanitizeSegment(entry));
+  if (normalized.length === 0) return "misc";
+  return normalized.join("/");
+}
+
+function splitFilename(filename: string | null): { stem: string; ext: string } {
+  if (!filename) return { stem: "file", ext: "" };
+  const base = path.basename(filename).trim();
+  if (!base) return { stem: "file", ext: "" };
+
+  const extRaw = path.extname(base);
+  const stemRaw = extRaw ? base.slice(0, base.length - extRaw.length) : base;
+  const stem = sanitizeSegment(stemRaw);
+  const ext = extRaw
+    .toLowerCase()
+    .replace(/[^a-z0-9.]/g, "")
+    .slice(0, 16);
+  return {
+    stem,
+    ext,
+  };
+}
+
+function ensureCompanyPrefix(companyId: string, objectKey: string): void {
+  const expectedPrefix = `${companyId}/`;
+  if (!objectKey.startsWith(expectedPrefix)) {
+    throw forbidden("Object does not belong to company");
+  }
+  if (objectKey.includes("..")) {
+    throw badRequest("Invalid object key");
+  }
+}
+
+function hashBuffer(input: Buffer): string {
+  return createHash("sha256").update(input).digest("hex");
+}
+
+function buildObjectKey(companyId: string, namespace: string, originalFilename: string | null): string {
+  const ns = normalizeNamespace(namespace);
+  const now = new Date();
+  const year = String(now.getUTCFullYear());
+  const month = String(now.getUTCMonth() + 1).padStart(2, "0");
+  const day = String(now.getUTCDate()).padStart(2, "0");
+  const { stem, ext } = splitFilename(originalFilename);
+  const suffix = randomUUID();
+  const filename = `${suffix}-${stem}${ext}`;
+  return `${companyId}/${ns}/${year}/${month}/${day}/${filename}`;
+}
+
+function assertPutFileInput(input: PutFileInput): void {
+  if (!input.companyId || input.companyId.trim().length === 0) {
+    throw unprocessable("companyId is required");
+  }
+  if (!input.namespace || input.namespace.trim().length === 0) {
+    throw unprocessable("namespace is required");
+  }
+  if (!input.contentType || input.contentType.trim().length === 0) {
+    throw unprocessable("contentType is required");
+  }
+  if (!(input.body instanceof Buffer)) {
+    throw unprocessable("body must be a Buffer");
+  }
+  if (input.body.length <= 0) {
+    throw unprocessable("File is empty");
+  }
+}
+
+export function createStorageService(provider: StorageProvider): StorageService {
+  return {
+    provider: provider.id,
+
+    async putFile(input: PutFileInput): Promise<PutFileResult> {
+      assertPutFileInput(input);
+      const objectKey = buildObjectKey(input.companyId, input.namespace, input.originalFilename);
+      const byteSize = input.body.length;
+      const contentType = input.contentType.trim().toLowerCase();
+      await provider.putObject({
+        objectKey,
+        body: input.body,
+        contentType,
+        contentLength: byteSize,
+      });
+
+      return {
+        provider: provider.id,
+        objectKey,
+        contentType,
+        byteSize,
+        sha256: hashBuffer(input.body),
+        originalFilename: input.originalFilename,
+      };
+    },
+
+    async getObject(companyId: string, objectKey: string) {
+      ensureCompanyPrefix(companyId, objectKey);
+      return provider.getObject({ objectKey });
+    },
+
+    async headObject(companyId: string, objectKey: string) {
+      ensureCompanyPrefix(companyId, objectKey);
+      return provider.headObject({ objectKey });
+    },
+
+    async deleteObject(companyId: string, objectKey: string) {
+      ensureCompanyPrefix(companyId, objectKey);
+      await provider.deleteObject({ objectKey });
+    },
+  };
+}

package/server/src/storage/types.ts

@@ -0,0 +1,63 @@
+import type { StorageProvider as StorageProviderId } from "@corporateai/shared";
+import type { Readable } from "node:stream";
+
+export interface PutObjectInput {
+  objectKey: string;
+  body: Buffer;
+  contentType: string;
+  contentLength: number;
+}
+
+export interface GetObjectInput {
+  objectKey: string;
+}
+
+export interface GetObjectResult {
+  stream: Readable;
+  contentType?: string;
+  contentLength?: number;
+  etag?: string;
+  lastModified?: Date;
+}
+
+export interface HeadObjectResult {
+  exists: boolean;
+  contentType?: string;
+  contentLength?: number;
+  etag?: string;
+  lastModified?: Date;
+}
+
+export interface StorageProvider {
+  id: StorageProviderId;
+  putObject(input: PutObjectInput): Promise<void>;
+  getObject(input: GetObjectInput): Promise<GetObjectResult>;
+  headObject(input: GetObjectInput): Promise<HeadObjectResult>;
+  deleteObject(input: GetObjectInput): Promise<void>;
+}
+
+export interface PutFileInput {
+  companyId: string;
+  namespace: string;
+  originalFilename: string | null;
+  contentType: string;
+  body: Buffer;
+}
+
+export interface PutFileResult {
+  provider: StorageProviderId;
+  objectKey: string;
+  contentType: string;
+  byteSize: number;
+  sha256: string;
+  originalFilename: string | null;
+}
+
+export interface StorageService {
+  provider: StorageProviderId;
+  putFile(input: PutFileInput): Promise<PutFileResult>;
+  getObject(companyId: string, objectKey: string): Promise<GetObjectResult>;
+  headObject(companyId: string, objectKey: string): Promise<HeadObjectResult>;
+  deleteObject(companyId: string, objectKey: string): Promise<void>;
+}
+