vault-sdk-prod 1.0.0 → 2.2.1

package/src/utils/file.js

@@ -0,0 +1,270 @@
+/**
+ * File helpers for uploads: reading whatever the caller passed as a file,
+ * resolving its MIME type, and reporting sizes.
+ */
+
+import fs from "fs";
+import { VaultError } from "./validationError.js";
+
+export const MAX_FILE_SIZE = 10 * 1024 * 1024 * 1024;
+
+/** Largest buffer this runtime can allocate; reading past it aborts the process. */
+export const MAX_BUFFERABLE_SIZE =
+  Buffer?.constants?.MAX_LENGTH ?? Buffer?.kMaxLength ?? 2 ** 31 - 1;
+
+/** Extension → MIME type */
+const CONTENT_TYPES = {
+  pdf: "application/pdf",
+  doc: "application/msword",
+  docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  txt: "text/plain",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  png: "image/png",
+  gif: "image/gif",
+  mp4: "video/mp4",
+  mp3: "audio/mpeg",
+  zip: "application/zip",
+  json: "application/json",
+  csv: "text/csv",
+};
+
+/**
+ * MIME type for a file name, falling back to "application/octet-stream".
+ *
+ * @param {string} fileName
+ * @returns {string}
+ */
+export function contentTypeFor(fileName) {
+  const extension = String(fileName).split(".").pop()?.toLowerCase();
+  return CONTENT_TYPES[extension] || "application/octet-stream";
+}
+
+/** Last path segment of a path or name, for both "/" and "\" separators. */
+export const baseName = (filePath) =>
+  String(filePath).split(/[\\/]/).pop() || "";
+
+/** Human-readable byte count, e.g. "1.5 GB". Mirrors the backend formatter. */
+export function formatFileSize(bytes) {
+  if (!bytes) return "0 Bytes";
+  const k = 1024;
+  const sizes = ["Bytes", "KB", "MB", "GB", "TB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return `${Math.round((bytes / k ** i) * 100) / 100} ${sizes[i]}`;
+}
+
+/** Anything byte-shaped → a Buffer, or null when the value isn't bytes. */
+export function toBuffer(value) {
+  if (Buffer.isBuffer(value)) return value;
+  if (value instanceof ArrayBuffer) return Buffer.from(value);
+  if (ArrayBuffer.isView(value)) {
+    return Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+  }
+  return null;
+}
+
+/**
+ * Reject a file that is too large, before its bytes are read into memory.
+ *
+ * @param {number} size - Size in bytes
+ * @param {string} name - File name, used in the message
+ * @param {string} operation - Calling method name
+ * @throws {VaultError} With code FILE_TOO_LARGE
+ */
+export function assertNotTooLarge(size, name, operation) {
+  if (!Number.isFinite(size)) return;
+
+  const limit = Math.min(MAX_FILE_SIZE, MAX_BUFFERABLE_SIZE);
+  if (size > limit) {
+    const cap =
+      limit === MAX_FILE_SIZE
+        ? `the maximum upload size of ${formatFileSize(MAX_FILE_SIZE)}`
+        : `what this runtime can hold in memory (${formatFileSize(limit)})`;
+    throw new VaultError(
+      `[Vault SDK] '${operation}': "${name}" is ${formatFileSize(size)}, which exceeds ${cap}.`,
+      { code: "FILE_TOO_LARGE", operation }
+    );
+  }
+}
+
+/** The working directory, when the runtime has one. */
+const defaultUploadRoot = () =>
+  typeof process !== "undefined" && typeof process.cwd === "function"
+    ? process.cwd()
+    : null;
+
+/**
+ * Resolve a caller-supplied path and confirm it stays inside `root`.
+ *
+ * Both sides go through realpath first, so a symlink cannot step out of the
+ * root. Messages name the file only, never the resolved path.
+ */
+async function resolveWithinRoot(filePath, root, fail) {
+  if (
+    typeof fs?.promises?.realpath !== "function" ||
+    typeof fs?.promises?.stat !== "function"
+  ) {
+    fail(
+      "Reading files from disk is not available here. Pass a File/Blob or { buffer, name } instead of a path.",
+      "FILE_READ_FAILED"
+    );
+  }
+
+  const configuredRoot = root || defaultUploadRoot();
+  if (!configuredRoot) {
+    fail(
+      "No upload directory is configured, so paths on disk cannot be read. Set VAULT_UPLOAD_ROOT, or pass { buffer, name } instead.",
+      "PATH_NOT_ALLOWED"
+    );
+  }
+
+  let realRoot;
+  try {
+    realRoot = await fs.promises.realpath(configuredRoot);
+  } catch {
+    fail(
+      "The configured upload directory does not exist. Check VAULT_UPLOAD_ROOT.",
+      "PATH_NOT_ALLOWED"
+    );
+  }
+
+  let realPath;
+  try {
+    realPath = await fs.promises.realpath(filePath);
+  } catch (error) {
+    fail(
+      `Could not read "${baseName(filePath)}" — ${error.code || error.message}.`,
+      "FILE_READ_FAILED"
+    );
+  }
+
+  const separator = realRoot.includes("\\") ? "\\" : "/";
+  const caseInsensitive = /^[A-Za-z]:/.test(realRoot);
+  const normalize = (value) => (caseInsensitive ? value.toLowerCase() : value);
+  const base = normalize(
+    realRoot.endsWith(separator)
+      ? realRoot.slice(0, -separator.length)
+      : realRoot
+  );
+  const target = normalize(realPath);
+
+  if (target !== base && !target.startsWith(base + separator)) {
+    fail(
+      `"${baseName(filePath)}" is outside the allowed upload directory. ` +
+        `Pass a file inside it, set VAULT_UPLOAD_ROOT to the directory you upload from, or hand over { buffer, name } instead.`,
+      "PATH_NOT_ALLOWED"
+    );
+  }
+
+  return realPath;
+}
+
+/**
+ * Turn whatever the caller passed as `file` into { buffer, name, type }.
+ *
+ * Accepts a path on disk, a File/Blob, or an object carrying the bytes under
+ * any of the common property names, so callers only ever hand over a file.
+ *
+ * @param {string|Object|Blob} input - The file, in any supported form
+ * @param {string} operation - Calling method name, used in error messages
+ * @param {Object} [options] - { uploadRoot }: the directory paths must stay inside
+ * @returns {Promise<{buffer: Buffer, name: string, type: string|undefined}>}
+ * @throws {VaultError} If the file is unreadable, too large, or outside the upload root
+ */
+export async function resolveFile(input, operation, options = {}) {
+  const fail = (message, code = "INVALID_PARAMETER") => {
+    throw new VaultError(`[Vault SDK] '${operation}': ${message}`, {
+      code,
+      operation,
+    });
+  };
+
+  if (input === undefined || input === null || input === "") {
+    fail(
+      "The 'file' parameter is required. Pass a path on disk, a File/Blob, or an object like { buffer, name }."
+    );
+  }
+
+  const readPath = async (filePath) => {
+    const realPath = await resolveWithinRoot(filePath, options.uploadRoot, fail);
+
+    let stats;
+    try {
+      stats = await fs.promises.stat(realPath);
+    } catch (error) {
+      fail(
+        `Could not read "${baseName(filePath)}" — ${error.code || error.message}.`,
+        "FILE_READ_FAILED"
+      );
+    }
+
+    if (!stats.isFile()) {
+      fail(`"${baseName(filePath)}" is not a file.`, "FILE_READ_FAILED");
+    }
+
+    assertNotTooLarge(stats.size, baseName(filePath), operation);
+
+    try {
+      return await fs.promises.readFile(realPath);
+    } catch (error) {
+      fail(
+        `Could not read "${baseName(filePath)}" — ${error.code || error.message}.`,
+        "FILE_READ_FAILED"
+      );
+    }
+  };
+
+  // uploadFile("./photo.jpg", vaultId)
+  if (typeof input === "string") {
+    const buffer = await readPath(input);
+    return { buffer, name: baseName(input), type: undefined };
+  }
+
+  // A bare Buffer carries no name, so there is nothing to store it under.
+  if (toBuffer(input) && !input.name) {
+    fail(
+      "A raw buffer has no file name. Pass { buffer, name } instead, e.g. { buffer, name: 'document.pdf' }."
+    );
+  }
+
+  if (typeof input !== "object") {
+    fail(
+      "The 'file' parameter must be a path, a File/Blob, or an object like { buffer, name }."
+    );
+  }
+
+  const name =
+    input.name || input.fileName || input.filename || baseName(input.path || "");
+  const type = input.type || input.mimeType || input.contentType;
+
+  // File / Blob (browser, or Node 20+ globals)
+  if (typeof input.arrayBuffer === "function") {
+    assertNotTooLarge(input.size, name || "file", operation);
+    const buffer = Buffer.from(await input.arrayBuffer());
+    assertNotTooLarge(buffer.length, name || "file", operation);
+    return { buffer, name, type };
+  }
+
+  const raw = input.buffer ?? input.data ?? input.content ?? input.bytes;
+  const buffer = raw
+    ? toBuffer(raw)
+    : input.path
+      ? await readPath(input.path)
+      : null;
+
+  if (!buffer) {
+    fail(
+      "Could not read the file content. Provide file.buffer as a Buffer/Uint8Array, or file.path pointing at a file on disk."
+    );
+  }
+
+  if (!name) {
+    fail(
+      "file.name is required. Provide the file name as a non-empty string (e.g. 'document.pdf')."
+    );
+  }
+
+  assertNotTooLarge(buffer.length, name, operation);
+
+  return { buffer, name, type };
+}

package/src/utils/sanitizeFileName.js

@@ -0,0 +1,67 @@
+/**
+ * File name sanitization — mirrors the vault backend and frontend sanitizer so
+ * a name the SDK sends is the same name the server would have derived itself.
+ */
+
+export const MAX_FILENAME_LENGTH = 255;
+
+/** Windows rejects these as file names whatever the extension. */
+const RESERVED_NAMES = new Set([
+  "CON",
+  "PRN",
+  "AUX",
+  "NUL",
+  ...Array.from({ length: 9 }, (_, i) => `COM${i + 1}`),
+  ...Array.from({ length: 9 }, (_, i) => `LPT${i + 1}`),
+]);
+
+/** Illegal in a Windows path, a URL path segment, or both. */
+const ILLEGAL_CHARS = /[<>:"/\\|?*]/g;
+
+const foldToAscii = (value) =>
+  value
+    .normalize("NFKD")
+    .replace(/\p{M}/gu, "")
+    .replace(/[^\x20-\x7E]/g, "");
+
+/** Leading dots are stripped: hidden files and "../" are not names we store. */
+const tidy = (value) =>
+  foldToAscii(value)
+    .replace(ILLEGAL_CHARS, "")
+    .replace(/\s+/g, " ")
+    .replace(/^[\s.]+|[\s.]+$/g, "");
+
+/** Splits "report.final.pdf" into { base: "report.final", ext: "pdf" }. */
+export const splitExtension = (name) => {
+  const dot = name.lastIndexOf(".");
+  if (dot <= 0) return { base: name, ext: "" };
+  return { base: name.slice(0, dot), ext: name.slice(dot + 1) };
+};
+
+/**
+ * @param {string} name - Raw name as the caller supplied it
+ * @param {string} [fallback="file"] - Used when nothing usable survives.
+ * @returns {string} ASCII-safe name, at most MAX_FILENAME_LENGTH characters
+ *
+ */
+export function sanitizeFileName(name, fallback = "file") {
+  if (typeof name !== "string" || !name) return fallback;
+
+  const segment = name.split(/[\\/]/).pop() ?? "";
+  const { base, ext } = splitExtension(segment);
+
+  let safeBase = tidy(base) || fallback;
+  if (RESERVED_NAMES.has(safeBase.toUpperCase())) {
+    safeBase = `_${safeBase}`;
+  }
+
+  const safeExt = tidy(ext).slice(0, 32);
+  const suffix = safeExt ? `.${safeExt}` : "";
+
+  const room = Math.max(1, MAX_FILENAME_LENGTH - suffix.length);
+  const truncated = safeBase.slice(0, room).replace(/[\s.]+$/, "") || fallback;
+
+  if (!truncated) return "";
+
+  return `${truncated}${suffix}`;
+}

package/src/utils/validationError.js

@@ -14,7 +14,10 @@ export class ValidationError extends Error {
     this.param = param;
     this.expectedType = expectedType;
 
-    Error.captureStackTrace(this, ValidationError);
+    // Chrome and Node only: Safari and older Firefox throw on it.
+    if (typeof Error.captureStackTrace === "function") {
+      Error.captureStackTrace(this, ValidationError);
+    }
   }
 }
 
@@ -23,21 +26,53 @@ export class ValidationError extends Error {
  * Wraps HTTP errors with status codes and structured error data.
  */
 export class VaultError extends Error {
-  constructor(message, { status, code, operation, data } = {}) {
+  constructor(message, { status, code, operation, data, requestId } = {}) {
     super(message);
     this.name = "VaultError";
     this.status = status || null;
     this.code = code || "VAULT_ERROR";
     this.operation = operation || null;
     this.data = data || null;
+    this.requestId = requestId || null;
 
-    Error.captureStackTrace(this, VaultError);
+    // Chrome and Node only: Safari and older Firefox throw on it.
+    if (typeof Error.captureStackTrace === "function") {
+      Error.captureStackTrace(this, VaultError);
+    }
   }
 }
 
 /**
  * Maps HTTP status codes to user-friendly error descriptions.
  */
+/**
+ * Reduce a server error body to what an integrator may safely see.
+ *
+ * Upstream bodies can carry stack traces, database table names and internal
+ * hostnames, so only the message, code and request id cross the boundary.
+ *
+ * @param {*} body - Response body from the server
+ * @returns {{message?: string, code?: string, requestId?: string}|null}
+ */
+export function safeErrorDetails(body) {
+  if (!body || typeof body !== "object") return null;
+
+  const text = (value) =>
+    typeof value === "string" && value.trim() ? value.trim() : undefined;
+
+  const details = {
+    message: text(body.message) ?? text(body.error),
+    code: text(body.code),
+    requestId: text(body.requestId) ?? text(body.request_id),
+  };
+
+  for (const key of Object.keys(details)) {
+    if (details[key] === undefined) delete details[key];
+  }
+
+  return Object.keys(details).length ? details : null;
+}
+
 export const HTTP_ERROR_MAP = {
   400: { code: "BAD_REQUEST", description: "The request was invalid. Check your parameters." },
   401: { code: "UNAUTHORIZED", description: "Authentication failed. Verify your VAULT_ACCESS_KEY and VAULT_SECRET_KEY." },
@@ -51,12 +86,33 @@ export const HTTP_ERROR_MAP = {
   503: { code: "SERVICE_UNAVAILABLE", description: "The service is temporarily unavailable. Please try again later." },
 };
 
+// `typeof ""` and `typeof "abc"` both read as "string", which turns a rejected
+// empty field into "must be a valid string. Received: string." Name what was
+// actually wrong with the value instead.
+const describe = (value) => {
+  if (typeof value === "string") {
+    if (value === "") return "an empty string";
+    if (value.trim() === "") return "a blank string";
+    return "string";
+  }
+  if (Array.isArray(value)) return value.length === 0 ? "an empty array" : "array";
+  if (value === null) return "null";
+  if (typeof value === "number") {
+    if (Number.isNaN(value)) return "NaN";
+    if (!Number.isFinite(value)) return String(value);
+    if (value < 0) return `a negative number (${value})`;
+    if (!Number.isInteger(value)) return `a decimal (${value})`;
+  }
+  return typeof value;
+};
+
 export const validator = {
   types: {
     string: (value) => typeof value === "string" && value.trim() !== "",
     object: (value) => typeof value === "object" && value !== null,
     array: (value) => Array.isArray(value) && value.length > 0,
-    number: (value) => typeof value === "number" && !isNaN(value) && value >= 0,
+    number: (value) => Number.isFinite(value) && value >= 0,
+    integer: (value) => Number.isInteger(value) && value >= 0,
     boolean: (value) => typeof value === "boolean",
     function: (value) => typeof value === "function",
     buffer: (value) => Buffer.isBuffer(value) || (value instanceof Uint8Array),
@@ -71,9 +127,26 @@ export const validator = {
     }
 
     Object.entries(params).forEach(([param, config]) => {
-      const { value, type, required = true, custom, message } = config;
+      const { value, type, required = true, custom, message, rejectNull } = config;
+
+      if (value === null && rejectNull) {
+        throw new ValidationError(
+          operation,
+          param,
+          type,
+          message ||
+            `[Vault SDK] '${operation}': Parameter '${param}' must be a valid ${type}, or be left out entirely. Received: null.`
+        );
+      }
+
+      // An optional string left empty means "not supplied"; the string type
+      // rejects "", so without this `getFiles(vaultId)` throws on its own default.
+      const omitted =
+        value === undefined ||
+        value === null ||
+        (type === "string" && typeof value === "string" && value.trim() === "");
 
-      if ((value === undefined || value === null) && !required) {
+      if (omitted && !required) {
         return;
       }
 
@@ -88,11 +161,16 @@ export const validator = {
 
       const typeValidator = this.types[type];
       if (typeValidator && !typeValidator(value)) {
+        const blank =
+          type === "string" && typeof value === "string" && value.trim() === "";
         throw new ValidationError(
           operation,
           param,
           type,
-          message || `[Vault SDK] '${operation}': Parameter '${param}' must be a valid ${type}. Received: ${typeof value}.`
+          message ||
+            (blank
+              ? `[Vault SDK] '${operation}' requires a non-empty '${param}'.`
+              : `[Vault SDK] '${operation}': Parameter '${param}' must be a valid ${type}. Received: ${describe(value)}.`)
         );
       }