@awak-app/simy-cli 0.2.2 → 0.3.3

package/src/local-task-artifact-contract.js

@@ -0,0 +1,266 @@
+import { Buffer } from "node:buffer";
+
+import {
+  LOCAL_TASK_FILE_CAPABILITY_REGISTRY,
+  LocalTaskFileCapabilityError,
+  validateLocalTaskFile,
+  validateLocalTaskFileCollection,
+} from "./local-task-file-capabilities.js";
+
+export const MAX_LOCAL_TASK_ARTIFACT_REFS =
+  LOCAL_TASK_FILE_CAPABILITY_REGISTRY.output.max_files;
+export const MAX_LOCAL_TASK_ARTIFACT_MANIFEST_BYTES =
+  LOCAL_TASK_FILE_CAPABILITY_REGISTRY.output.max_manifest_bytes;
+export const MAX_LOCAL_TASK_ARTIFACT_ID_CHARS = 256;
+export const MAX_LOCAL_TASK_ARTIFACT_NAME_CHARS = 512;
+export const MAX_LOCAL_TASK_ARTIFACT_PATH_CHARS = 2_048;
+export const MAX_LOCAL_TASK_ARTIFACT_MIME_CHARS = 256;
+
+const ARTIFACT_ID_PATTERN = /^[A-Za-z0-9._:-]+$/;
+const SHA256_PATTERN = /^[a-f0-9]{64}$/i;
+const WINDOWS_DRIVE_PATH_PATTERN = /^[A-Za-z]:/;
+const CONTROL_CHARACTER_PATTERN = /[\u0000-\u001f\u007f]/;
+const ALLOWED_ARTIFACT_REF_FIELDS = new Set([
+  "id",
+  "local_task_id",
+  "name",
+  "relative_path",
+  "mime_type",
+  "size_bytes",
+  "sha256",
+  "verified",
+]);
+
+export class LocalTaskArtifactContractError extends Error {
+  constructor(message, {
+    field = null,
+    index = null,
+    code = "local_task_artifact_contract_invalid",
+    recoveryAction =
+      LOCAL_TASK_FILE_CAPABILITY_REGISTRY.recovery_actions.choose_supported_file,
+  } = {}) {
+    super(message);
+    this.name = "LocalTaskArtifactContractError";
+    this.code = code;
+    this.recovery_action = recoveryAction;
+    this.recovery = recoveryAction.id;
+    this.field = field;
+    this.index = index;
+  }
+}
+
+export function buildLocalTaskArtifactRefs(artifacts, localTaskId) {
+  const refs = Array.isArray(artifacts)
+    ? artifacts.map((artifact) => ({
+        id: artifact?.id,
+        local_task_id: localTaskId,
+        name: artifact?.name,
+        relative_path: artifact?.relative_path,
+        mime_type: artifact?.mime_type,
+        size_bytes: artifact?.size_bytes,
+        sha256: artifact?.sha256,
+        verified: artifact?.verified === true,
+      }))
+    : artifacts;
+  return validateLocalTaskArtifactRefs(refs, { expectedLocalTaskId: localTaskId });
+}
+
+export function validateLocalTaskArtifactRefs(
+  refs,
+  { expectedLocalTaskId = null } = {},
+) {
+  if (!Array.isArray(refs)) {
+    throw contractError("Local Task output metadata must be a list.");
+  }
+  if (refs.length > MAX_LOCAL_TASK_ARTIFACT_REFS) {
+    throw contractError(
+      `Local Task produced ${refs.length} output files; SIMY supports at most ${MAX_LOCAL_TASK_ARTIFACT_REFS}.`,
+    );
+  }
+
+  const validatedFiles = refs.map((artifact, index) =>
+    validateArtifactRef(artifact, index, expectedLocalTaskId));
+  try {
+    validateLocalTaskFileCollection(validatedFiles, { direction: "output" });
+  } catch (error) {
+    throw capabilityContractError(error);
+  }
+
+  const canonicalRefs = refs.map((artifact, index) =>
+    canonicalArtifactRef({ ...artifact, mime_type: validatedFiles[index].mime_type }));
+  const serialized = serializeCanonicalRefs(canonicalRefs);
+  const manifestBytes = Buffer.byteLength(serialized, "utf8");
+  if (manifestBytes > MAX_LOCAL_TASK_ARTIFACT_MANIFEST_BYTES) {
+    throw contractError(
+      `Local Task output metadata exceeds the ${MAX_LOCAL_TASK_ARTIFACT_MANIFEST_BYTES}-byte safety limit.`,
+    );
+  }
+  return canonicalRefs;
+}
+
+export function localTaskArtifactManifestBytes(refs) {
+  return Buffer.byteLength(
+    serializeCanonicalRefs(
+      Array.isArray(refs) ? refs.map(canonicalArtifactRef) : refs,
+    ),
+    "utf8",
+  );
+}
+
+export function serializeLocalTaskArtifactManifest(refs) {
+  return serializeCanonicalRefs(
+    Array.isArray(refs) ? refs.map(canonicalArtifactRef) : refs,
+  );
+}
+
+function validateArtifactRef(artifact, index, expectedLocalTaskId) {
+  if (!isRecord(artifact)) {
+    throw artifactError(index, "must be an object");
+  }
+  if (Object.keys(artifact).some((key) => !ALLOWED_ARTIFACT_REF_FIELDS.has(key))) {
+    throw artifactError(index, "contains unsupported metadata");
+  }
+
+  requireCanonicalString(artifact.id, {
+    index,
+    field: "id",
+    label: "identifier",
+    maxChars: MAX_LOCAL_TASK_ARTIFACT_ID_CHARS,
+    pattern: ARTIFACT_ID_PATTERN,
+  });
+  requireCanonicalString(artifact.local_task_id, {
+    index,
+    field: "local_task_id",
+    label: "Local Task identifier",
+    maxChars: MAX_LOCAL_TASK_ARTIFACT_ID_CHARS,
+    pattern: ARTIFACT_ID_PATTERN,
+  });
+  if (expectedLocalTaskId !== null && artifact.local_task_id !== expectedLocalTaskId) {
+    throw artifactError(index, "does not belong to this Local Task", "local_task_id");
+  }
+
+  requireCanonicalString(artifact.name, {
+    index,
+    field: "name",
+    label: "name",
+    maxChars: MAX_LOCAL_TASK_ARTIFACT_NAME_CHARS,
+    rejectControls: true,
+  });
+  if (/[\\/]/.test(artifact.name)) {
+    throw artifactError(index, "has a name containing a path separator", "name");
+  }
+
+  requireCanonicalString(artifact.relative_path, {
+    index,
+    field: "relative_path",
+    label: "relative path",
+    maxChars: MAX_LOCAL_TASK_ARTIFACT_PATH_CHARS,
+    rejectControls: true,
+  });
+  if (!isSafeRelativeArtifactPath(artifact.relative_path)) {
+    throw artifactError(index, "does not have a safe relative path", "relative_path");
+  }
+
+  requireCanonicalString(artifact.mime_type, {
+    index,
+    field: "mime_type",
+    label: "MIME type",
+    maxChars: MAX_LOCAL_TASK_ARTIFACT_MIME_CHARS,
+  });
+  if (typeof artifact.sha256 !== "string" || !SHA256_PATTERN.test(artifact.sha256)) {
+    throw artifactError(index, "has an invalid SHA-256 digest", "sha256");
+  }
+  if (artifact.verified !== true) {
+    throw artifactError(index, "was not verified", "verified");
+  }
+  try {
+    return validateLocalTaskFile({
+      name: artifact.name,
+      mime_type: artifact.mime_type,
+      size_bytes: artifact.size_bytes,
+      sha256: artifact.sha256,
+    }, { direction: "output" });
+  } catch (error) {
+    throw capabilityContractError(error, index);
+  }
+}
+
+function requireCanonicalString(
+  value,
+  { index, field, label, maxChars, pattern = null, rejectControls = false },
+) {
+  if (typeof value !== "string" || !value || value.trim() !== value) {
+    throw artifactError(index, `has an invalid ${label}`, field);
+  }
+  if (characterCount(value) > maxChars) {
+    throw artifactError(index, `has a ${label} longer than ${maxChars} characters`, field);
+  }
+  if (rejectControls && CONTROL_CHARACTER_PATTERN.test(value)) {
+    throw artifactError(index, `has a ${label} containing control characters`, field);
+  }
+  if (pattern && !pattern.test(value)) {
+    throw artifactError(index, `has an invalid ${label}`, field);
+  }
+}
+
+function isSafeRelativeArtifactPath(value) {
+  if (
+    value.startsWith("/") ||
+    /^~(?:\/|$)/.test(value) ||
+    WINDOWS_DRIVE_PATH_PATTERN.test(value) ||
+    value.includes("\\") ||
+    value.endsWith("/")
+  ) {
+    return false;
+  }
+  return value
+    .split("/")
+    .every((segment) => segment !== "" && segment !== "." && segment !== "..");
+}
+
+function characterCount(value) {
+  return value.length;
+}
+
+function canonicalArtifactRef(artifact) {
+  return {
+    id: artifact?.id,
+    local_task_id: artifact?.local_task_id,
+    name: artifact?.name,
+    relative_path: artifact?.relative_path,
+    mime_type: artifact?.mime_type,
+    size_bytes: artifact?.size_bytes,
+    sha256: artifact?.sha256,
+    verified: artifact?.verified,
+  };
+}
+
+function serializeCanonicalRefs(refs) {
+  try {
+    return JSON.stringify(refs);
+  } catch {
+    throw contractError("Local Task output metadata is not valid JSON.");
+  }
+}
+
+function artifactError(index, detail, field = null) {
+  return contractError(`Local Task output file ${index + 1} ${detail}.`, { index, field });
+}
+
+function contractError(message, details = {}) {
+  return new LocalTaskArtifactContractError(message, details);
+}
+
+function capabilityContractError(error, index = null) {
+  if (!(error instanceof LocalTaskFileCapabilityError)) throw error;
+  return contractError(error.message, {
+    index,
+    field: error.field,
+    code: error.code,
+    recoveryAction: error.recovery_action,
+  });
+}
+
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}

package/src/local-task-attachment-store.js

@@ -0,0 +1,447 @@
+import { createHash, randomUUID } from "node:crypto";
+import {
+  chmod,
+  lstat,
+  mkdir,
+  open,
+  readFile,
+  realpath,
+  readdir,
+  rm,
+  stat,
+} from "node:fs/promises";
+import path from "node:path";
+
+import {
+  LOCAL_TASK_ATTACHMENT_REF_VERSION,
+  LOCAL_TASK_FILE_CAPABILITY_REGISTRY,
+  LOCAL_TASK_FILE_CAPABILITY_VERSION,
+  LocalTaskFileCapabilityError,
+  validateLocalTaskFile,
+  validateLocalTaskFileCollection,
+} from "./local-task-file-capabilities.js";
+
+const SAFE_IDEMPOTENCY_KEY = /^[A-Za-z0-9][A-Za-z0-9._:-]{15,127}$/;
+const SAFE_DEVICE_ID = /^[A-Za-z0-9._:-]{1,256}$/;
+const SAFE_STAGE_ID = /^[a-f0-9]{64}$/;
+const SAFE_ATTACHMENT_ID = /^attachment_[A-Za-z0-9-]{36}$/;
+const REF_FIELDS = new Set([
+  "schema_version",
+  "capability_version",
+  "stage_id",
+  "attachment_id",
+  "device_id",
+  "name",
+  "mime_type",
+  "size_bytes",
+  "sha256",
+]);
+const STAGING_RETENTION_MS = 24 * 60 * 60 * 1_000;
+const STAGING_MAX_STAGES = 20;
+const STAGING_MAX_BYTES = 200 * 1024 * 1024;
+
+export function createLocalTaskAttachmentStore({ root }) {
+  if (!root) throw new TypeError("root is required");
+  const storageRoot = path.resolve(root);
+  let stageQueue = Promise.resolve();
+  const withStageLock = async (operation) => {
+    const previous = stageQueue;
+    let release;
+    stageQueue = new Promise((resolve) => {
+      release = resolve;
+    });
+    await previous;
+    try {
+      return await operation();
+    } finally {
+      release();
+    }
+  };
+
+  return {
+    root: storageRoot,
+    async cleanupExpired({
+      now = Date.now(),
+      retentionMs = STAGING_RETENTION_MS,
+    } = {}) {
+      let entries;
+      try {
+        entries = await readdir(storageRoot, { withFileTypes: true });
+      } catch (error) {
+        if (error?.code === "ENOENT") return 0;
+        throw error;
+      }
+      let removed = 0;
+      for (const entry of entries) {
+        if (!entry.isDirectory() || !SAFE_STAGE_ID.test(entry.name)) continue;
+        const stageRoot = resolveStageRoot(storageRoot, entry.name);
+        const manifestPath = path.join(stageRoot, "manifest.json");
+        let timestamp = Number.NaN;
+        try {
+          const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+          timestamp = Date.parse(manifest.created_at);
+          if (!Number.isFinite(timestamp)) {
+            timestamp = (await stat(stageRoot)).mtimeMs;
+          }
+        } catch {
+          timestamp = (await stat(stageRoot)).mtimeMs;
+        }
+        if (now - timestamp <= retentionMs) continue;
+        await rm(stageRoot, { recursive: true, force: true });
+        removed += 1;
+      }
+      return removed;
+    },
+    async stage({ deviceId, idempotencyKey, files }) {
+      return withStageLock(async () => {
+      await this.cleanupExpired();
+      const normalizedDeviceId = requireDeviceId(deviceId);
+      const key = requireIdempotencyKey(idempotencyKey);
+      if (!Array.isArray(files) || files.length === 0) {
+        throw storeError(
+          "Choose at least one file to attach.",
+          "local_task_attachment_required",
+          "reattach_file",
+        );
+      }
+      const validated = validateLocalTaskFileCollection(files, {
+        direction: "input",
+        requireBytes: true,
+      });
+      const stageId = digest(`${normalizedDeviceId}\0${key}`);
+      const fingerprint = digest(JSON.stringify(validated.map((file) => ({
+        name: file.name,
+        mime_type: file.mime_type,
+        size_bytes: file.size_bytes,
+        sha256: file.sha256,
+      }))));
+      const stageRoot = resolveStageRoot(storageRoot, stageId);
+      const manifestPath = path.join(stageRoot, "manifest.json");
+
+      try {
+        const existing = JSON.parse(await readFile(manifestPath, "utf8"));
+        if (
+          existing.device_id !== normalizedDeviceId ||
+          existing.fingerprint !== fingerprint
+        ) {
+          throw storeError(
+            "These files differ from the first request using this idempotency key.",
+            "local_task_attachment_idempotency_conflict",
+            "reattach_file",
+          );
+        }
+        return { refs: existing.refs, replayed: true };
+      } catch (error) {
+        if (error instanceof LocalTaskFileCapabilityError) throw error;
+        if (error?.code !== "ENOENT") throw error;
+      }
+
+      const usage = await stagingUsage(storageRoot);
+      const incomingBytes = validated.reduce(
+        (total, file) => total + file.size_bytes,
+        0,
+      );
+      if (
+        usage.stages >= STAGING_MAX_STAGES ||
+        usage.bytes + incomingBytes > STAGING_MAX_BYTES
+      ) {
+        throw storeError(
+          "SIMY is already holding several attached files. Finish or retry the active tasks, then attach these files again.",
+          "local_task_attachment_staging_quota_exceeded",
+          "remove_extra_files",
+        );
+      }
+
+      await mkdir(storageRoot, { recursive: true, mode: 0o700 });
+      await mkdir(stageRoot, { recursive: false, mode: 0o700 });
+      const refs = [];
+      const entries = [];
+      try {
+        for (const [index, file] of files.entries()) {
+          const normalized = validated[index];
+          const attachmentId = `attachment_${randomUUID()}`;
+          const storageName = `${attachmentId}.bin`;
+          const target = path.join(stageRoot, storageName);
+          await writeExclusive(target, Buffer.from(file.bytes));
+          const ref = {
+            schema_version: LOCAL_TASK_ATTACHMENT_REF_VERSION,
+            capability_version: LOCAL_TASK_FILE_CAPABILITY_VERSION,
+            stage_id: stageId,
+            attachment_id: attachmentId,
+            device_id: normalizedDeviceId,
+            name: normalized.name,
+            mime_type: normalized.mime_type,
+            size_bytes: normalized.size_bytes,
+            sha256: normalized.sha256,
+          };
+          refs.push(ref);
+          entries.push({ ...ref, storage_name: storageName });
+        }
+        await writeExclusive(manifestPath, Buffer.from(JSON.stringify({
+          schema_version: LOCAL_TASK_ATTACHMENT_REF_VERSION,
+          capability_version: LOCAL_TASK_FILE_CAPABILITY_VERSION,
+          stage_id: stageId,
+          device_id: normalizedDeviceId,
+          fingerprint,
+          refs,
+          entries,
+          created_at: new Date().toISOString(),
+        })));
+        return { refs, replayed: false };
+      } catch (error) {
+        await rm(stageRoot, { recursive: true, force: true });
+        throw error;
+      }
+      });
+    },
+
+    async materialize({ refs, deviceId, inputsRoot }) {
+      const normalizedDeviceId = requireDeviceId(deviceId);
+      const values = validateRefs(refs, normalizedDeviceId);
+      if (values.length === 0) return [];
+      const targetRoot = path.resolve(inputsRoot);
+      await mkdir(targetRoot, { recursive: true, mode: 0o700 });
+      const materialized = [];
+
+      for (const ref of values) {
+        const stageRoot = resolveStageRoot(storageRoot, ref.stage_id);
+        const manifest = await readManifest(stageRoot);
+        const entry = manifest.entries?.find(
+          (value) => value.attachment_id === ref.attachment_id,
+        );
+        if (!entry || !sameRef(entry, ref)) {
+          throw storeError(
+            `${ref.name} is no longer available on this desktop.`,
+            "local_task_attachment_ref_not_found",
+            "reattach_file",
+          );
+        }
+        const source = path.join(stageRoot, entry.storage_name);
+        await assertManagedRegularFile(source, stageRoot);
+        const bytes = await readFile(source);
+        const validated = validateLocalTaskFile({
+          ...ref,
+          bytes,
+        }, { direction: "input", requireBytes: true });
+        const localPath = path.join(
+          targetRoot,
+          `${ref.attachment_id}-${validated.name}`,
+        );
+        await writeExclusive(localPath, bytes);
+        materialized.push({
+          id: ref.attachment_id,
+          name: validated.name,
+          mime_type: validated.mime_type,
+          size_bytes: validated.size_bytes,
+          sha256: validated.sha256,
+          local_path: localPath,
+          integrity_status: "verified",
+          staged_at: manifest.created_at,
+          executor_handoff_status: "pending",
+          delivered_at: null,
+          cleanup_status: "not_required",
+          cleaned_at: null,
+          cleanup_error: null,
+          storage: "managed_copy",
+          capability_version: validated.capability_version,
+        });
+      }
+      return materialized;
+    },
+
+    async cleanup({ refs, deviceId }) {
+      const normalizedDeviceId = requireDeviceId(deviceId);
+      const values = validateRefs(refs, normalizedDeviceId);
+      const stageIds = new Set(values.map((ref) => ref.stage_id));
+      for (const stageId of stageIds) {
+        await rm(resolveStageRoot(storageRoot, stageId), {
+          recursive: true,
+          force: true,
+        });
+      }
+    },
+  };
+}
+
+async function stagingUsage(storageRoot) {
+  let entries;
+  try {
+    entries = await readdir(storageRoot, { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === "ENOENT") return { stages: 0, bytes: 0 };
+    throw error;
+  }
+  let stages = 0;
+  let bytes = 0;
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !SAFE_STAGE_ID.test(entry.name)) continue;
+    stages += 1;
+    try {
+      const manifest = JSON.parse(
+        await readFile(path.join(storageRoot, entry.name, "manifest.json"), "utf8"),
+      );
+      for (const ref of Array.isArray(manifest.refs) ? manifest.refs : []) {
+        if (Number.isSafeInteger(ref?.size_bytes) && ref.size_bytes > 0) {
+          bytes += ref.size_bytes;
+        }
+      }
+    } catch {
+      // A corrupt local stage still consumes a stage slot and is removed by
+      // normal expiry; never trust it to report a smaller byte count.
+      bytes = STAGING_MAX_BYTES;
+    }
+  }
+  return { stages, bytes };
+}
+
+function validateRefs(refs, deviceId) {
+  if (!Array.isArray(refs)) {
+    throw storeError(
+      "The attached-file references are invalid.",
+      "local_task_attachment_ref_invalid",
+      "reattach_file",
+    );
+  }
+  if (refs.length > LOCAL_TASK_FILE_CAPABILITY_REGISTRY.input.max_files) {
+    throw storeError(
+      "Too many attached-file references were provided.",
+      "local_task_files_count_exceeded",
+      "remove_extra_files",
+    );
+  }
+  return refs.map((ref) => {
+    if (
+      !ref ||
+      typeof ref !== "object" ||
+      Array.isArray(ref) ||
+      Object.keys(ref).some((key) => !REF_FIELDS.has(key)) ||
+      ref.schema_version !== LOCAL_TASK_ATTACHMENT_REF_VERSION ||
+      ref.capability_version !== LOCAL_TASK_FILE_CAPABILITY_VERSION ||
+      !SAFE_STAGE_ID.test(String(ref.stage_id || "")) ||
+      !SAFE_ATTACHMENT_ID.test(String(ref.attachment_id || "")) ||
+      ref.device_id !== deviceId
+    ) {
+      const versionMismatch =
+        ref?.schema_version !== LOCAL_TASK_ATTACHMENT_REF_VERSION ||
+        ref?.capability_version !== LOCAL_TASK_FILE_CAPABILITY_VERSION;
+      throw storeError(
+        versionMismatch
+          ? "SIMY CLI must be updated before these files can be used."
+          : "These files were attached from another desktop session.",
+        versionMismatch
+          ? "local_task_attachment_version_unsupported"
+          : "local_task_attachment_wrong_device",
+        versionMismatch ? "update_cli" : "reattach_file",
+      );
+    }
+    validateLocalTaskFile(ref, { direction: "input" });
+    return { ...ref };
+  });
+}
+
+async function readManifest(stageRoot) {
+  try {
+    const manifestPath = path.join(stageRoot, "manifest.json");
+    await assertManagedRegularFile(manifestPath, stageRoot);
+    const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+    if (
+      manifest.schema_version !== LOCAL_TASK_ATTACHMENT_REF_VERSION ||
+      manifest.capability_version !== LOCAL_TASK_FILE_CAPABILITY_VERSION
+    ) {
+      throw storeError(
+        "SIMY CLI must be updated before these files can be used.",
+        "local_task_attachment_version_unsupported",
+        "update_cli",
+      );
+    }
+    return manifest;
+  } catch (error) {
+    if (error instanceof LocalTaskFileCapabilityError) throw error;
+    throw storeError(
+      "The attached files are no longer available on this desktop.",
+      "local_task_attachment_ref_not_found",
+      "reattach_file",
+    );
+  }
+}
+
+async function assertManagedRegularFile(value, parent) {
+  const details = await lstat(value);
+  if (!details.isFile() || details.isSymbolicLink()) {
+    throw storeError(
+      "The attached file failed SIMY's safety check.",
+      "local_task_attachment_unsafe_storage",
+      "reattach_file",
+    );
+  }
+  const [resolved, resolvedParent] = await Promise.all([
+    realpath(value),
+    realpath(parent),
+  ]);
+  if (!resolved.startsWith(`${resolvedParent}${path.sep}`)) {
+    throw storeError(
+      "The attached file failed SIMY's safety check.",
+      "local_task_attachment_unsafe_storage",
+      "reattach_file",
+    );
+  }
+}
+
+async function writeExclusive(target, bytes) {
+  const handle = await open(target, "wx", 0o600);
+  try {
+    await handle.writeFile(bytes);
+  } finally {
+    await handle.close();
+  }
+  await chmod(target, 0o600);
+}
+
+function sameRef(entry, ref) {
+  return [...REF_FIELDS].every((key) => entry[key] === ref[key]);
+}
+
+function requireDeviceId(value) {
+  const id = String(value || "");
+  if (!SAFE_DEVICE_ID.test(id)) {
+    throw storeError(
+      "Reconnect SIMY CLI before attaching files.",
+      "local_task_attachment_device_unavailable",
+      "reattach_file",
+    );
+  }
+  return id;
+}
+
+function requireIdempotencyKey(value) {
+  const key = String(value || "");
+  if (!SAFE_IDEMPOTENCY_KEY.test(key)) {
+    throw storeError(
+      "Attach the files again to create a new upload request.",
+      "local_task_attachment_idempotency_key_invalid",
+      "reattach_file",
+    );
+  }
+  return key;
+}
+
+function resolveStageRoot(root, stageId) {
+  if (!SAFE_STAGE_ID.test(stageId)) throw new TypeError("invalid stage id");
+  const resolved = path.resolve(root, stageId);
+  if (!resolved.startsWith(`${path.resolve(root)}${path.sep}`)) {
+    throw new TypeError("invalid stage root");
+  }
+  return resolved;
+}
+
+function digest(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function storeError(message, code, recoveryId) {
+  return new LocalTaskFileCapabilityError(message, {
+    code,
+    recoveryAction:
+      LOCAL_TASK_FILE_CAPABILITY_REGISTRY.recovery_actions[recoveryId],
+  });
+}