create-windy 0.5.2 → 0.6.0

package/template/apps/server/src/report-staging/native/archive-frame-helper.c

@@ -0,0 +1,309 @@
+#include <archive.h>
+#include <archive_entry.h>
+#include <errno.h>
+#include <fcntl.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/stat.h>
+#include <unistd.h>
+
+#ifndef O_CLOEXEC
+#define O_CLOEXEC 0
+#endif
+#ifndef O_NOFOLLOW
+#define O_NOFOLLOW 0
+#endif
+
+#define CHUNK_BYTES (64U * 1024U)
+#define MAX_PATH_BYTES 4096U
+
+enum frame_type {
+  FRAME_FILE = 1,
+  FRAME_DIRECTORY = 2,
+  FRAME_DATA = 3,
+  FRAME_ENTRY_END = 4,
+  FRAME_ARCHIVE_END = 5,
+};
+
+static const unsigned char MAGIC[8] = {'W', 'R', 'S', 'F', 1, 0, 0, 0};
+
+struct volume_data {
+  const char *path;
+  int fd;
+  unsigned char *buffer;
+  uint64_t size;
+  uint64_t bytes_read;
+  int opened;
+  int exhausted;
+};
+
+static int fail(const char *message) {
+  (void)fprintf(stderr, "windy-report-archive: %s\n", message);
+  return 1;
+}
+
+static int write_all(const void *value, size_t length) {
+  const unsigned char *cursor = value;
+  while (length > 0) {
+    ssize_t written = write(STDOUT_FILENO, cursor, length);
+    if (written < 0 && errno == EINTR) continue;
+    if (written <= 0) return -1;
+    cursor += (size_t)written;
+    length -= (size_t)written;
+  }
+  return 0;
+}
+
+static int volume_open(struct archive *reader, void *client_data) {
+  struct volume_data *volume = client_data;
+  (void)reader;
+  if (volume->opened) return ARCHIVE_FATAL;
+  volume->fd = open(volume->path, O_RDONLY | O_CLOEXEC | O_NOFOLLOW);
+  if (volume->fd < 0) return ARCHIVE_FATAL;
+  struct stat metadata;
+  if (fstat(volume->fd, &metadata) != 0 || !S_ISREG(metadata.st_mode) ||
+      metadata.st_size < 0) {
+    close(volume->fd);
+    volume->fd = -1;
+    return ARCHIVE_FATAL;
+  }
+  volume->size = (uint64_t)metadata.st_size;
+  volume->buffer = malloc(CHUNK_BYTES);
+  if (volume->buffer == NULL) {
+    close(volume->fd);
+    volume->fd = -1;
+    return ARCHIVE_FATAL;
+  }
+  volume->opened = 1;
+  return ARCHIVE_OK;
+}
+
+static la_ssize_t volume_read(struct archive *reader, void *client_data,
+                              const void **buffer) {
+  struct volume_data *volume = client_data;
+  (void)reader;
+  *buffer = volume->buffer;
+  for (;;) {
+    ssize_t count = read(volume->fd, volume->buffer, CHUNK_BYTES);
+    if (count < 0 && errno == EINTR) continue;
+    if (count < 0) return -1;
+    if (count == 0) volume->exhausted = 1;
+    if (count > 0) {
+      if ((uint64_t)count > UINT64_MAX - volume->bytes_read) return -1;
+      volume->bytes_read += (uint64_t)count;
+    }
+    return (la_ssize_t)count;
+  }
+}
+
+static int volume_close(struct archive *reader, void *client_data) {
+  struct volume_data *volume = client_data;
+  (void)reader;
+  if (volume->fd >= 0) close(volume->fd);
+  free(volume->buffer);
+  volume->fd = -1;
+  volume->buffer = NULL;
+  return ARCHIVE_OK;
+}
+
+static int volume_switch(struct archive *reader, void *previous,
+                         void *next) {
+  struct volume_data *old_volume = previous;
+  if (!old_volume->exhausted) return ARCHIVE_FATAL;
+  if (volume_close(reader, previous) != ARCHIVE_OK) return ARCHIVE_FATAL;
+  return volume_open(reader, next);
+}
+
+static int open_volumes(struct archive *reader, char **filenames,
+                        size_t count, struct volume_data **output) {
+  struct volume_data *volumes = calloc(count, sizeof(*volumes));
+  if (volumes == NULL) return ARCHIVE_FATAL;
+  for (size_t index = 0; index < count; index++) {
+    volumes[index].path = filenames[index];
+    volumes[index].fd = -1;
+    if (archive_read_append_callback_data(reader, &volumes[index]) !=
+        ARCHIVE_OK) {
+      free(volumes);
+      return ARCHIVE_FATAL;
+    }
+  }
+  if (archive_read_set_open_callback(reader, volume_open) != ARCHIVE_OK ||
+      archive_read_set_read_callback(reader, volume_read) != ARCHIVE_OK ||
+      archive_read_set_close_callback(reader, volume_close) != ARCHIVE_OK ||
+      archive_read_set_switch_callback(reader, volume_switch) != ARCHIVE_OK ||
+      archive_read_open1(reader) != ARCHIVE_OK) {
+    archive_read_free(reader);
+    free(volumes);
+    return ARCHIVE_FATAL;
+  }
+  *output = volumes;
+  return ARCHIVE_OK;
+}
+
+static int all_volumes_consumed(struct archive *reader,
+                                struct volume_data *volumes, size_t count) {
+  la_int64_t consumed = archive_filter_bytes(reader, -1);
+  uint64_t last_volume_start = 0;
+  if (consumed < 0) return 0;
+  for (size_t index = 0; index < count; index++) {
+    if (!volumes[index].opened || volumes[index].bytes_read == 0) return 0;
+    if (index + 1 < count && !volumes[index].exhausted) return 0;
+    if (index + 1 < count) {
+      if (volumes[index].size > UINT64_MAX - last_volume_start) return 0;
+      last_volume_start += volumes[index].size;
+    }
+  }
+  return (uint64_t)consumed > last_volume_start;
+}
+
+static void put_u32(unsigned char output[4], uint32_t value) {
+  output[0] = (unsigned char)(value >> 24);
+  output[1] = (unsigned char)(value >> 16);
+  output[2] = (unsigned char)(value >> 8);
+  output[3] = (unsigned char)value;
+}
+
+static void put_u64(unsigned char output[8], uint64_t value) {
+  for (unsigned int index = 0; index < 8; index++) {
+    output[7U - index] = (unsigned char)(value >> (index * 8U));
+  }
+}
+
+static int write_frame(enum frame_type type, const void *payload,
+                       uint32_t length) {
+  unsigned char header[5];
+  header[0] = (unsigned char)type;
+  put_u32(&header[1], length);
+  if (write_all(header, sizeof(header)) != 0) return -1;
+  if (length > 0 && write_all(payload, length) != 0) return -1;
+  return 0;
+}
+
+static int write_entry(enum frame_type type, const char *path,
+                       uint64_t declared_size) {
+  size_t path_length = strlen(path);
+  if (path_length == 0 || path_length > MAX_PATH_BYTES) return -1;
+  uint32_t payload_length = 12U + (uint32_t)path_length;
+  unsigned char *payload = malloc(payload_length);
+  if (payload == NULL) return -1;
+  put_u32(payload, (uint32_t)path_length);
+  put_u64(&payload[4], declared_size);
+  memcpy(&payload[12], path, path_length);
+  int result = write_frame(type, payload, payload_length);
+  free(payload);
+  return result;
+}
+
+static int stream_regular(struct archive *reader, uint64_t declared_size) {
+  unsigned char buffer[CHUNK_BYTES];
+  uint64_t actual_size = 0;
+  for (;;) {
+    size_t filled = 0;
+    while (filled < sizeof(buffer)) {
+      ssize_t count = archive_read_data(reader, &buffer[filled],
+                                        sizeof(buffer) - filled);
+      if (count < 0) return -1;
+      if (count == 0) break;
+      if ((uint64_t)count > UINT64_MAX - actual_size) return -1;
+      actual_size += (uint64_t)count;
+      filled += (size_t)count;
+    }
+    if (filled > 0 &&
+        write_frame(FRAME_DATA, buffer, (uint32_t)filled) != 0) {
+      return -1;
+    }
+    if (filled < sizeof(buffer)) break;
+  }
+  return actual_size == declared_size ? 0 : -1;
+}
+
+static int release_reader(struct archive *reader, struct volume_data *volumes,
+                          const char *message) {
+  archive_read_free(reader);
+  free(volumes);
+  return fail(message);
+}
+
+static int run_archive(char **filenames, size_t volume_count) {
+  struct archive *reader = archive_read_new();
+  if (reader == NULL) return fail("reader allocation failed");
+  if (archive_read_support_filter_all(reader) != ARCHIVE_OK ||
+      archive_read_support_format_all(reader) != ARCHIVE_OK) {
+    archive_read_free(reader);
+    return fail("format initialization failed");
+  }
+  struct volume_data *volumes = NULL;
+  if (open_volumes(reader, filenames, volume_count, &volumes) != ARCHIVE_OK)
+    return fail("archive open failed");
+  if (write_all(MAGIC, sizeof(MAGIC)) != 0) {
+    return release_reader(reader, volumes, "output failed");
+  }
+
+  struct archive_entry *entry = NULL;
+  int status;
+  uint64_t entry_count = 0;
+  while ((status = archive_read_next_header(reader, &entry)) == ARCHIVE_OK) {
+    const char *path = archive_entry_pathname_utf8(entry);
+    mode_t type = archive_entry_filetype(entry);
+    if (path == NULL || strlen(path) == 0 || strlen(path) > MAX_PATH_BYTES) {
+      return release_reader(reader, volumes, "invalid entry path");
+    }
+    if (archive_entry_is_encrypted(entry) != 0 ||
+        archive_entry_hardlink(entry) != NULL ||
+        archive_entry_symlink(entry) != NULL) {
+      return release_reader(reader, volumes, "unsupported entry type");
+    }
+    if (type != AE_IFREG && type != AE_IFDIR) {
+      return release_reader(reader, volumes, "unsupported entry type");
+    }
+    if (!archive_entry_size_is_set(entry) || archive_entry_size(entry) < 0) {
+      return release_reader(reader, volumes, "invalid entry size");
+    }
+    uint64_t declared_size = (uint64_t)archive_entry_size(entry);
+    if (type == AE_IFDIR && declared_size != 0) {
+      return release_reader(reader, volumes, "invalid directory size");
+    }
+    enum frame_type frame_type =
+        type == AE_IFDIR ? FRAME_DIRECTORY : FRAME_FILE;
+    if (write_entry(frame_type, path, declared_size) != 0) {
+      return release_reader(reader, volumes, "output failed");
+    }
+    if (type == AE_IFREG && stream_regular(reader, declared_size) != 0) {
+      return release_reader(reader, volumes, "entry read failed");
+    }
+    if (type == AE_IFDIR && archive_read_data_skip(reader) != ARCHIVE_OK) {
+      return release_reader(reader, volumes, "entry read failed");
+    }
+    if (write_frame(FRAME_ENTRY_END, NULL, 0) != 0) {
+      return release_reader(reader, volumes, "output failed");
+    }
+    if (entry_count == UINT64_MAX) {
+      return release_reader(reader, volumes, "entry count overflow");
+    }
+    entry_count++;
+  }
+  if (status != ARCHIVE_EOF || entry_count == 0 ||
+      archive_read_has_encrypted_entries(reader) != 0 ||
+      !all_volumes_consumed(reader, volumes, volume_count)) {
+    return release_reader(reader, volumes, "archive read failed");
+  }
+  if (archive_read_close(reader) != ARCHIVE_OK) {
+    return release_reader(reader, volumes, "archive close failed");
+  }
+  if (archive_read_free(reader) != ARCHIVE_OK) {
+    free(volumes);
+    return fail("archive close failed");
+  }
+  free(volumes);
+  if (write_frame(FRAME_ARCHIVE_END, NULL, 0) != 0) {
+    return fail("output failed");
+  }
+  return 0;
+}
+
+int main(int argc, char **argv) {
+  if (argc < 2) return fail("volume path required");
+  return run_archive(&argv[1], (size_t)(argc - 1));
+}

package/template/apps/server/src/report-staging/path-policy.test.ts

@@ -0,0 +1,127 @@
+import { describe, expect, test } from "bun:test";
+import {
+  ModuleReportStagingError,
+  type ModuleReportStagingPolicyV1,
+} from "@southwind-ai/server-sdk";
+import {
+  ArchivePathCollector,
+  validateExpandedSourceRelativePaths,
+  validateSourceRelativePaths,
+} from "./path-policy.js";
+
+describe("报告暂存路径策略", () => {
+  test("接受 NFC 业务相对路径并生成稳定 path key", () => {
+    const collector = new ArchivePathCollector(policy());
+    collector.add("好友/张三.txt");
+    collector.add("图片/");
+    expect(collector.values()).toMatchObject([
+      { relativePath: "好友/张三.txt", directory: false },
+      { relativePath: "图片", directory: true },
+    ]);
+    expect(collector.values()[0]?.pathKey).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  test.each([
+    "/etc/passwd",
+    "../secret",
+    "C:/secret",
+    "\\\\server\\share",
+    "a//b",
+    "a/./b",
+    "a/\u0000b",
+    "e\u0301.txt",
+  ])("拒绝绝对、dot、控制符和非 NFC 路径：%s", (path) => {
+    const collector = new ArchivePathCollector(policy());
+    expect(() => collector.add(path)).toThrow(ModuleReportStagingError);
+  });
+
+  test("大小写折叠、重复、路径深度和 source 漂移 fail closed", () => {
+    const collector = new ArchivePathCollector(policy());
+    collector.add("A/File.txt");
+    expect(() => collector.add("a/file.txt")).toThrow("大小写折叠");
+    expect(() => collector.add("1/2/3/4/5.txt")).toThrow("路径深度");
+    expect(() =>
+      validateSourceRelativePaths(["part1.rar", "PART1.RAR"], 4),
+    ).toThrow("大小写折叠");
+  });
+
+  test("Unicode full-style casefold 和声明容量在解压前 fail closed", () => {
+    const collector = new ArchivePathCollector(policy());
+    collector.add("Straße/Σ.txt", { byteSize: 5 });
+    expect(() => collector.add("STRASSE/ς.TXT", { byteSize: 5 })).toThrow(
+      "大小写折叠",
+    );
+
+    const oversized = new ArchivePathCollector(policy());
+    expect(() =>
+      oversized.add("large.bin", { byteSize: policy().maxEntryBytes + 1 }),
+    ).toThrow("声明大小");
+  });
+
+  test.each([
+    ["В.txt", "ᲀ.txt"],
+    ["ͅ.txt", "Ι.txt"],
+  ])("Unicode full casefold 拒绝非简单小写等价路径：%s / %s", (left, right) => {
+    const collector = new ArchivePathCollector(policy());
+    collector.add(left);
+    expect(() => collector.add(right)).toThrow("大小写折叠");
+  });
+
+  test("文件/目录前缀冲突及隐式目录总量在解压前 fail closed", () => {
+    const parentFile = new ArchivePathCollector(policy());
+    parentFile.add("messages", { byteSize: 1 });
+    expect(() => parentFile.add("messages/a.txt", { byteSize: 1 })).toThrow(
+      "层级冲突",
+    );
+
+    expect(() =>
+      validateSourceRelativePaths(["parts/a.rar", "parts"], 4),
+    ).toThrow("层级冲突");
+
+    const nodes = new ArchivePathCollector({ ...policy(), maxEntries: 3 });
+    expect(() => nodes.add("a/b/c.txt", { byteSize: 1 })).not.toThrow();
+    expect(() => nodes.add("d.txt", { byteSize: 1 })).toThrow("隐式目录");
+  });
+
+  test("expanded 源文件也受 entry 与隐式目录总量约束", () => {
+    expect(() =>
+      validateExpandedSourceRelativePaths(
+        ["report/index.html", "report/assets/app.js"],
+        { ...policy(), maxEntries: 4 },
+      ),
+    ).not.toThrow();
+    expect(() =>
+      validateExpandedSourceRelativePaths(
+        ["report/index.html", "report/assets/app.js"],
+        { ...policy(), maxEntries: 3 },
+      ),
+    ).toThrow("隐式目录");
+  });
+
+  test("V1 PostgreSQL path 边界接受 4096 UTF-8 bytes 并拒绝 4097", () => {
+    expect(() =>
+      validateSourceRelativePaths([`${"界".repeat(1_365)}a`], 1),
+    ).not.toThrow();
+    expect(() =>
+      validateSourceRelativePaths([`${"界".repeat(1_365)}ab`], 1),
+    ).toThrow("不安全的相对路径");
+  });
+});
+
+function policy(): ModuleReportStagingPolicyV1 {
+  return {
+    purpose: "evidence.report-staging",
+    sourcePurposes: ["evidence.original"],
+    retentionMs: 60_000,
+    claimTtlMs: 30_000,
+    maxReadLeaseMs: 10_000,
+    maxProcessMs: 10_000,
+    maxSources: 4,
+    maxArchiveBytes: 1_024,
+    maxExpandedBytes: 4_096,
+    maxEntryBytes: 2_048,
+    maxEntries: 8,
+    maxCompressionRatio: 100,
+    maxPathDepth: 4,
+  };
+}

package/template/apps/server/src/report-staging/path-policy.ts

@@ -0,0 +1,263 @@
+import { createHash } from "node:crypto";
+import { posix } from "node:path";
+import {
+  MODULE_REPORT_STAGING_MAX_ENTRIES,
+  MODULE_REPORT_STAGING_PATH_MAX_BYTES,
+  ModuleReportStagingError,
+  type ModuleReportStagingPolicyV1,
+} from "@southwind-ai/server-sdk";
+import { caseFold } from "unicode-case-folding";
+
+const WINDOWS_DRIVE = /^[a-zA-Z]:/;
+
+export interface ValidatedArchivePath {
+  readonly relativePath: string;
+  readonly pathKey: string;
+  readonly directory: boolean;
+  readonly byteSize: number;
+}
+
+export function validateSourceRelativePaths(
+  paths: readonly string[],
+  maxDepth: number,
+): string[] {
+  return validateUniquePaths(paths, maxDepth, false).map(
+    ({ relativePath }) => relativePath,
+  );
+}
+
+export function validateExpandedSourceRelativePaths(
+  paths: readonly string[],
+  policy: ModuleReportStagingPolicyV1,
+): string[] {
+  const collector = new ArchivePathCollector(policy);
+  paths.forEach((path) =>
+    collector.add(path, { directory: false, byteSize: 0 }),
+  );
+  return collector.values().map(({ relativePath }) => relativePath);
+}
+
+export class ArchivePathCollector {
+  readonly #paths: ValidatedArchivePath[] = [];
+  readonly #exact = new Set<string>();
+  readonly #folded = new Set<string>();
+  readonly #fileKeys = new Set<string>();
+  readonly #requiredDirectoryKeys = new Set<string>();
+  readonly #nodeKeys = new Set<string>();
+  #expandedByteSize = 0;
+
+  constructor(private readonly policy: ModuleReportStagingPolicyV1) {}
+
+  add(
+    raw: string,
+    metadata: {
+      readonly directory?: boolean;
+      readonly byteSize?: number;
+    } = {},
+  ): void {
+    if (
+      this.#paths.length >= this.policy.maxEntries ||
+      this.#paths.length >= MODULE_REPORT_STAGING_MAX_ENTRIES
+    ) {
+      throw unsafe("报告 entry 数量超过 Host 策略");
+    }
+    const directory = metadata.directory ?? raw.endsWith("/");
+    const byteSize = metadata.byteSize ?? 0;
+    if (
+      !Number.isSafeInteger(byteSize) ||
+      byteSize < 0 ||
+      (directory && byteSize !== 0)
+    ) {
+      throw unsafe("报告 entry 声明大小无效");
+    }
+    if (!directory && byteSize > this.policy.maxEntryBytes) {
+      throw limit("报告 entry 声明大小超过 Host 策略");
+    }
+    const nextExpandedBytes = this.#expandedByteSize + byteSize;
+    if (
+      !Number.isSafeInteger(nextExpandedBytes) ||
+      nextExpandedBytes > this.policy.maxExpandedBytes
+    ) {
+      throw limit("报告声明展开大小超过 Host 策略");
+    }
+    const path = validatePath(
+      raw,
+      this.policy.maxPathDepth,
+      true,
+      directory,
+      byteSize,
+    );
+    const key = unicodePathCasefold(path.relativePath);
+    if (this.#exact.has(path.relativePath) || this.#folded.has(key)) {
+      throw unsafe("报告包含重复或大小写折叠冲突路径");
+    }
+    const nodeKeys = registerPathTree(
+      key,
+      directory,
+      this.#fileKeys,
+      this.#requiredDirectoryKeys,
+      () => unsafe("报告路径存在文件与目录层级冲突"),
+    );
+    const newNodeCount = nodeKeys.reduce(
+      (count, nodeKey) => count + Number(!this.#nodeKeys.has(nodeKey)),
+      this.#nodeKeys.size,
+    );
+    if (newNodeCount > this.policy.maxEntries) {
+      throw limit("报告隐式目录与 entry 总量超过 Host 策略");
+    }
+    this.#exact.add(path.relativePath);
+    this.#folded.add(key);
+    nodeKeys.forEach((nodeKey) => this.#nodeKeys.add(nodeKey));
+    this.#paths.push(path);
+    this.#expandedByteSize = nextExpandedBytes;
+  }
+
+  values(): readonly ValidatedArchivePath[] {
+    return this.#paths;
+  }
+
+  get expandedByteSize(): number {
+    return this.#expandedByteSize;
+  }
+}
+
+export function validateExtractedRelativePath(
+  value: string,
+  maxDepth: number,
+): ValidatedArchivePath {
+  return validatePath(value, maxDepth, false, false, 0);
+}
+
+export function validateArchiveEntryPath(
+  raw: string,
+  policy: ModuleReportStagingPolicyV1,
+  directory: boolean,
+  byteSize: number,
+) {
+  return validatePath(raw, policy.maxPathDepth, true, directory, byteSize);
+}
+
+export function unicodePathCasefold(value: string): string {
+  return caseFold(value.normalize("NFKC")).normalize("NFC");
+}
+
+function validateUniquePaths(
+  paths: readonly string[],
+  maxDepth: number,
+  allowDirectory: boolean,
+): ValidatedArchivePath[] {
+  const exact = new Set<string>();
+  const folded = new Set<string>();
+  const fileKeys = new Set<string>();
+  const requiredDirectoryKeys = new Set<string>();
+  return paths.map((raw) => {
+    const path = validatePath(
+      raw,
+      maxDepth,
+      allowDirectory,
+      allowDirectory && raw.endsWith("/"),
+      0,
+    );
+    const key = unicodePathCasefold(path.relativePath);
+    if (exact.has(path.relativePath) || folded.has(key)) {
+      throw invalid("报告源路径重复或大小写折叠冲突");
+    }
+    registerPathTree(key, path.directory, fileKeys, requiredDirectoryKeys, () =>
+      invalid("报告源路径存在文件与目录层级冲突"),
+    );
+    exact.add(path.relativePath);
+    folded.add(key);
+    return path;
+  });
+}
+
+function registerPathTree(
+  key: string,
+  directory: boolean,
+  fileKeys: Set<string>,
+  requiredDirectoryKeys: Set<string>,
+  onConflict: () => ModuleReportStagingError,
+) {
+  const segments = key.split("/");
+  const ancestors = segments
+    .slice(0, -1)
+    .map((_, index) => segments.slice(0, index + 1).join("/"));
+  if (
+    ancestors.some((ancestor) => fileKeys.has(ancestor)) ||
+    (!directory && requiredDirectoryKeys.has(key))
+  ) {
+    throw onConflict();
+  }
+  ancestors.forEach((ancestor) => requiredDirectoryKeys.add(ancestor));
+  if (!directory) fileKeys.add(key);
+  return [...ancestors, key];
+}
+
+function validatePath(
+  raw: string,
+  maxDepth: number,
+  allowDirectory: boolean,
+  directory: boolean,
+  byteSize: number,
+): ValidatedArchivePath {
+  if (directory && !allowDirectory) {
+    throw unsafe("报告 entry 类型不符合 Host 策略");
+  }
+  const value = directory && raw.endsWith("/") ? raw.slice(0, -1) : raw;
+  if (
+    !value ||
+    value !== value.normalize("NFC") ||
+    hasControlCharacter(value) ||
+    value.includes("\\") ||
+    value.startsWith("/") ||
+    value.startsWith("//") ||
+    WINDOWS_DRIVE.test(value) ||
+    Buffer.byteLength(value, "utf8") > MODULE_REPORT_STAGING_PATH_MAX_BYTES
+  ) {
+    throw unsafe("报告包含不安全的相对路径");
+  }
+  const segments = value.split("/");
+  if (
+    segments.length > maxDepth ||
+    segments.some(
+      (segment) =>
+        !segment ||
+        segment === "." ||
+        segment === ".." ||
+        segment !== segment.trim(),
+    )
+  ) {
+    throw unsafe("报告路径深度或分段不符合 Host 策略");
+  }
+  const normalized = posix.normalize(value);
+  if (normalized !== value || normalized.startsWith("../")) {
+    throw unsafe("报告路径规范化后发生漂移");
+  }
+  return {
+    relativePath: value,
+    pathKey: createHash("sha256")
+      .update(unicodePathCasefold(value))
+      .digest("hex"),
+    directory,
+    byteSize,
+  };
+}
+
+function hasControlCharacter(value: string) {
+  return [...value].some((character) => {
+    const point = character.codePointAt(0)!;
+    return point <= 0x1f || point === 0x7f;
+  });
+}
+
+function unsafe(message: string) {
+  return new ModuleReportStagingError("REPORT_STAGING_UNSAFE_ARCHIVE", message);
+}
+
+function invalid(message: string) {
+  return new ModuleReportStagingError("REPORT_STAGING_INVALID_INPUT", message);
+}
+
+function limit(message: string) {
+  return new ModuleReportStagingError("REPORT_STAGING_LIMIT", message);
+}