@aigne/afs-provider-utils 1.11.0-beta.12

package/LICENSE.md

@@ -0,0 +1,26 @@
+# Proprietary License
+
+Copyright (c) 2024-2025 ArcBlock, Inc. All Rights Reserved.
+
+This software and associated documentation files (the "Software") are proprietary
+and confidential. Unauthorized copying, modification, distribution, or use of
+this Software, via any medium, is strictly prohibited.
+
+The Software is provided for internal use only within ArcBlock, Inc. and its
+authorized affiliates.
+
+## No License Granted
+
+No license, express or implied, is granted to any party for any purpose.
+All rights are reserved by ArcBlock, Inc.
+
+## Public Artifact Distribution
+
+Portions of this Software may be released publicly under separate open-source
+licenses (such as MIT License) through designated public repositories. Such
+public releases are governed by their respective licenses and do not affect
+the proprietary nature of this repository.
+
+## Contact
+
+For licensing inquiries, contact: legal@arcblock.io

package/dist/index.cjs

@@ -0,0 +1,8 @@
+const require_local_path = require('./local-path.cjs');
+const require_mime = require('./mime.cjs');
+const require_path_guard = require('./path-guard.cjs');
+
+exports.assertPathWithinRoot = require_path_guard.assertPathWithinRoot;
+exports.getMimeType = require_mime.getMimeType;
+exports.isBinaryFile = require_mime.isBinaryFile;
+exports.resolveLocalPath = require_local_path.resolveLocalPath;

package/dist/index.d.cts

@@ -0,0 +1,4 @@
+import { ResolveLocalPathOptions, resolveLocalPath } from "./local-path.cjs";
+import { getMimeType, isBinaryFile } from "./mime.cjs";
+import { assertPathWithinRoot } from "./path-guard.cjs";
+export { type ResolveLocalPathOptions, assertPathWithinRoot, getMimeType, isBinaryFile, resolveLocalPath };

package/dist/index.d.mts

@@ -0,0 +1,4 @@
+import { ResolveLocalPathOptions, resolveLocalPath } from "./local-path.mjs";
+import { getMimeType, isBinaryFile } from "./mime.mjs";
+import { assertPathWithinRoot } from "./path-guard.mjs";
+export { type ResolveLocalPathOptions, assertPathWithinRoot, getMimeType, isBinaryFile, resolveLocalPath };

package/dist/index.mjs

@@ -0,0 +1,5 @@
+import { resolveLocalPath } from "./local-path.mjs";
+import { getMimeType, isBinaryFile } from "./mime.mjs";
+import { assertPathWithinRoot } from "./path-guard.mjs";
+
+export { assertPathWithinRoot, getMimeType, isBinaryFile, resolveLocalPath };

package/dist/local-path.cjs

@@ -0,0 +1,17 @@
+let node_path = require("node:path");
+
+//#region src/local-path.ts
+function resolveLocalPath(rawPath, options) {
+	if (rawPath === ".") return process.cwd();
+	let resolved = rawPath.replaceAll("${CWD}", process.cwd());
+	if (resolved.startsWith("~/")) {
+		const home = process.env.HOME;
+		if (!home) throw new Error("Cannot resolve '~/' path: HOME environment variable is not set");
+		resolved = (0, node_path.join)(home, resolved.slice(2));
+	}
+	if (!(0, node_path.isAbsolute)(resolved)) resolved = (0, node_path.join)(options?.cwd || process.cwd(), resolved);
+	return resolved;
+}
+
+//#endregion
+exports.resolveLocalPath = resolveLocalPath;

package/dist/local-path.d.cts

@@ -0,0 +1,8 @@
+//#region src/local-path.d.ts
+interface ResolveLocalPathOptions {
+  cwd?: string;
+}
+declare function resolveLocalPath(rawPath: string, options?: ResolveLocalPathOptions): string;
+//#endregion
+export { ResolveLocalPathOptions, resolveLocalPath };
+//# sourceMappingURL=local-path.d.cts.map

package/dist/local-path.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-path.d.cts","names":[],"sources":["../src/local-path.ts"],"mappings":";UAEiB,uBAAA;EACf,GAAA;AAAA;AAAA,iBAGc,gBAAA,CAAiB,OAAA,UAAiB,OAAA,GAAU,uBAAA"}

package/dist/local-path.d.mts

@@ -0,0 +1,8 @@
+//#region src/local-path.d.ts
+interface ResolveLocalPathOptions {
+  cwd?: string;
+}
+declare function resolveLocalPath(rawPath: string, options?: ResolveLocalPathOptions): string;
+//#endregion
+export { ResolveLocalPathOptions, resolveLocalPath };
+//# sourceMappingURL=local-path.d.mts.map

package/dist/local-path.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-path.d.mts","names":[],"sources":["../src/local-path.ts"],"mappings":";UAEiB,uBAAA;EACf,GAAA;AAAA;AAAA,iBAGc,gBAAA,CAAiB,OAAA,UAAiB,OAAA,GAAU,uBAAA"}

package/dist/local-path.mjs

@@ -0,0 +1,18 @@
+import { isAbsolute, join } from "node:path";
+
+//#region src/local-path.ts
+function resolveLocalPath(rawPath, options) {
+	if (rawPath === ".") return process.cwd();
+	let resolved = rawPath.replaceAll("${CWD}", process.cwd());
+	if (resolved.startsWith("~/")) {
+		const home = process.env.HOME;
+		if (!home) throw new Error("Cannot resolve '~/' path: HOME environment variable is not set");
+		resolved = join(home, resolved.slice(2));
+	}
+	if (!isAbsolute(resolved)) resolved = join(options?.cwd || process.cwd(), resolved);
+	return resolved;
+}
+
+//#endregion
+export { resolveLocalPath };
+//# sourceMappingURL=local-path.mjs.map

package/dist/local-path.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-path.mjs","names":[],"sources":["../src/local-path.ts"],"sourcesContent":["import { isAbsolute, join } from \"node:path\";\n\nexport interface ResolveLocalPathOptions {\n  cwd?: string;\n}\n\nexport function resolveLocalPath(rawPath: string, options?: ResolveLocalPathOptions): string {\n  if (rawPath === \".\") {\n    return process.cwd();\n  }\n\n  let resolved = rawPath.replaceAll(\"${CWD}\", process.cwd());\n\n  if (resolved.startsWith(\"~/\")) {\n    const home = process.env.HOME;\n    if (!home) {\n      throw new Error(\"Cannot resolve '~/' path: HOME environment variable is not set\");\n    }\n    resolved = join(home, resolved.slice(2));\n  }\n\n  if (!isAbsolute(resolved)) {\n    resolved = join(options?.cwd || process.cwd(), resolved);\n  }\n\n  return resolved;\n}\n"],"mappings":";;;AAMA,SAAgB,iBAAiB,SAAiB,SAA2C;AAC3F,KAAI,YAAY,IACd,QAAO,QAAQ,KAAK;CAGtB,IAAI,WAAW,QAAQ,WAAW,UAAU,QAAQ,KAAK,CAAC;AAE1D,KAAI,SAAS,WAAW,KAAK,EAAE;EAC7B,MAAM,OAAO,QAAQ,IAAI;AACzB,MAAI,CAAC,KACH,OAAM,IAAI,MAAM,iEAAiE;AAEnF,aAAW,KAAK,MAAM,SAAS,MAAM,EAAE,CAAC;;AAG1C,KAAI,CAAC,WAAW,SAAS,CACvB,YAAW,KAAK,SAAS,OAAO,QAAQ,KAAK,EAAE,SAAS;AAG1D,QAAO"}

package/dist/mime.cjs

@@ -0,0 +1,53 @@
+let node_path = require("node:path");
+
+//#region src/mime.ts
+const MIME_TYPES = {
+	png: "image/png",
+	jpg: "image/jpeg",
+	jpeg: "image/jpeg",
+	gif: "image/gif",
+	bmp: "image/bmp",
+	webp: "image/webp",
+	svg: "image/svg+xml",
+	ico: "image/x-icon",
+	pdf: "application/pdf",
+	txt: "text/plain",
+	md: "text/markdown",
+	js: "text/javascript",
+	ts: "text/typescript",
+	json: "application/json",
+	html: "text/html",
+	css: "text/css",
+	xml: "text/xml"
+};
+const BINARY_EXTENSIONS = new Set([
+	"png",
+	"jpg",
+	"jpeg",
+	"gif",
+	"bmp",
+	"webp",
+	"ico",
+	"pdf",
+	"zip",
+	"tar",
+	"gz",
+	"exe",
+	"dll",
+	"so",
+	"dylib",
+	"wasm"
+]);
+function getExtension(filePath) {
+	return (0, node_path.basename)(filePath).split(".").pop()?.toLowerCase() || "";
+}
+function getMimeType(filePath) {
+	return MIME_TYPES[getExtension(filePath)] || "application/octet-stream";
+}
+function isBinaryFile(filePath) {
+	return BINARY_EXTENSIONS.has(getExtension(filePath));
+}
+
+//#endregion
+exports.getMimeType = getMimeType;
+exports.isBinaryFile = isBinaryFile;

package/dist/mime.d.cts

@@ -0,0 +1,6 @@
+//#region src/mime.d.ts
+declare function getMimeType(filePath: string): string;
+declare function isBinaryFile(filePath: string): boolean;
+//#endregion
+export { getMimeType, isBinaryFile };
+//# sourceMappingURL=mime.d.cts.map

package/dist/mime.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mime.d.cts","names":[],"sources":["../src/mime.ts"],"mappings":";iBAgDgB,WAAA,CAAY,QAAA;AAAA,iBAIZ,YAAA,CAAa,QAAA"}

package/dist/mime.d.mts

@@ -0,0 +1,6 @@
+//#region src/mime.d.ts
+declare function getMimeType(filePath: string): string;
+declare function isBinaryFile(filePath: string): boolean;
+//#endregion
+export { getMimeType, isBinaryFile };
+//# sourceMappingURL=mime.d.mts.map

package/dist/mime.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mime.d.mts","names":[],"sources":["../src/mime.ts"],"mappings":";iBAgDgB,WAAA,CAAY,QAAA;AAAA,iBAIZ,YAAA,CAAa,QAAA"}

package/dist/mime.mjs

@@ -0,0 +1,53 @@
+import { basename } from "node:path";
+
+//#region src/mime.ts
+const MIME_TYPES = {
+	png: "image/png",
+	jpg: "image/jpeg",
+	jpeg: "image/jpeg",
+	gif: "image/gif",
+	bmp: "image/bmp",
+	webp: "image/webp",
+	svg: "image/svg+xml",
+	ico: "image/x-icon",
+	pdf: "application/pdf",
+	txt: "text/plain",
+	md: "text/markdown",
+	js: "text/javascript",
+	ts: "text/typescript",
+	json: "application/json",
+	html: "text/html",
+	css: "text/css",
+	xml: "text/xml"
+};
+const BINARY_EXTENSIONS = new Set([
+	"png",
+	"jpg",
+	"jpeg",
+	"gif",
+	"bmp",
+	"webp",
+	"ico",
+	"pdf",
+	"zip",
+	"tar",
+	"gz",
+	"exe",
+	"dll",
+	"so",
+	"dylib",
+	"wasm"
+]);
+function getExtension(filePath) {
+	return basename(filePath).split(".").pop()?.toLowerCase() || "";
+}
+function getMimeType(filePath) {
+	return MIME_TYPES[getExtension(filePath)] || "application/octet-stream";
+}
+function isBinaryFile(filePath) {
+	return BINARY_EXTENSIONS.has(getExtension(filePath));
+}
+
+//#endregion
+export { getMimeType, isBinaryFile };
+//# sourceMappingURL=mime.mjs.map

package/dist/mime.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"mime.mjs","names":[],"sources":["../src/mime.ts"],"sourcesContent":["import { basename } from \"node:path\";\n\nconst MIME_TYPES: Record<string, string> = {\n  // Images\n  png: \"image/png\",\n  jpg: \"image/jpeg\",\n  jpeg: \"image/jpeg\",\n  gif: \"image/gif\",\n  bmp: \"image/bmp\",\n  webp: \"image/webp\",\n  svg: \"image/svg+xml\",\n  ico: \"image/x-icon\",\n  // Documents\n  pdf: \"application/pdf\",\n  txt: \"text/plain\",\n  md: \"text/markdown\",\n  // Code\n  js: \"text/javascript\",\n  ts: \"text/typescript\",\n  json: \"application/json\",\n  html: \"text/html\",\n  css: \"text/css\",\n  xml: \"text/xml\",\n};\n\nconst BINARY_EXTENSIONS = new Set([\n  \"png\",\n  \"jpg\",\n  \"jpeg\",\n  \"gif\",\n  \"bmp\",\n  \"webp\",\n  \"ico\",\n  \"pdf\",\n  \"zip\",\n  \"tar\",\n  \"gz\",\n  \"exe\",\n  \"dll\",\n  \"so\",\n  \"dylib\",\n  \"wasm\",\n]);\n\nfunction getExtension(filePath: string): string {\n  return basename(filePath).split(\".\").pop()?.toLowerCase() || \"\";\n}\n\nexport function getMimeType(filePath: string): string {\n  return MIME_TYPES[getExtension(filePath)] || \"application/octet-stream\";\n}\n\nexport function isBinaryFile(filePath: string): boolean {\n  return BINARY_EXTENSIONS.has(getExtension(filePath));\n}\n"],"mappings":";;;AAEA,MAAM,aAAqC;CAEzC,KAAK;CACL,KAAK;CACL,MAAM;CACN,KAAK;CACL,KAAK;CACL,MAAM;CACN,KAAK;CACL,KAAK;CAEL,KAAK;CACL,KAAK;CACL,IAAI;CAEJ,IAAI;CACJ,IAAI;CACJ,MAAM;CACN,MAAM;CACN,KAAK;CACL,KAAK;CACN;AAED,MAAM,oBAAoB,IAAI,IAAI;CAChC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD,CAAC;AAEF,SAAS,aAAa,UAA0B;AAC9C,QAAO,SAAS,SAAS,CAAC,MAAM,IAAI,CAAC,KAAK,EAAE,aAAa,IAAI;;AAG/D,SAAgB,YAAY,UAA0B;AACpD,QAAO,WAAW,aAAa,SAAS,KAAK;;AAG/C,SAAgB,aAAa,UAA2B;AACtD,QAAO,kBAAkB,IAAI,aAAa,SAAS,CAAC"}

package/dist/path-guard.cjs

@@ -0,0 +1,34 @@
+let node_path = require("node:path");
+let node_fs_promises = require("node:fs/promises");
+let _aigne_afs = require("@aigne/afs");
+
+//#region src/path-guard.ts
+/**
+* Assert that a resolved path stays within the given root directory.
+* Performs both logical path check and realpath-based symlink check.
+*/
+async function assertPathWithinRoot(fullPath, rootDir) {
+	const mountRoot = (0, node_path.resolve)(rootDir);
+	const resolved = (0, node_path.resolve)(fullPath);
+	if (resolved !== mountRoot && !resolved.startsWith(`${mountRoot}/`)) throw new _aigne_afs.AFSError("Path traversal is not allowed", "AFS_PERMISSION_DENIED");
+	try {
+		let real;
+		try {
+			real = await (0, node_fs_promises.realpath)(resolved);
+		} catch {
+			const parent = (0, node_path.dirname)(resolved);
+			try {
+				real = await (0, node_fs_promises.realpath)(parent);
+			} catch {
+				return;
+			}
+		}
+		const realMountRoot = await (0, node_fs_promises.realpath)(mountRoot);
+		if (real !== realMountRoot && !real.startsWith(`${realMountRoot}/`)) throw new _aigne_afs.AFSError("Path traversal via symlink is not allowed", "AFS_PERMISSION_DENIED");
+	} catch (error) {
+		if (error instanceof _aigne_afs.AFSError) throw error;
+	}
+}
+
+//#endregion
+exports.assertPathWithinRoot = assertPathWithinRoot;

package/dist/path-guard.d.cts

@@ -0,0 +1,9 @@
+//#region src/path-guard.d.ts
+/**
+ * Assert that a resolved path stays within the given root directory.
+ * Performs both logical path check and realpath-based symlink check.
+ */
+declare function assertPathWithinRoot(fullPath: string, rootDir: string): Promise<void>;
+//#endregion
+export { assertPathWithinRoot };
+//# sourceMappingURL=path-guard.d.cts.map

package/dist/path-guard.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-guard.d.cts","names":[],"sources":["../src/path-guard.ts"],"mappings":";;AAQA;;;iBAAsB,oBAAA,CAAqB,QAAA,UAAkB,OAAA,WAAkB,OAAA"}

package/dist/path-guard.d.mts

@@ -0,0 +1,9 @@
+//#region src/path-guard.d.ts
+/**
+ * Assert that a resolved path stays within the given root directory.
+ * Performs both logical path check and realpath-based symlink check.
+ */
+declare function assertPathWithinRoot(fullPath: string, rootDir: string): Promise<void>;
+//#endregion
+export { assertPathWithinRoot };
+//# sourceMappingURL=path-guard.d.mts.map

package/dist/path-guard.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-guard.d.mts","names":[],"sources":["../src/path-guard.ts"],"mappings":";;AAQA;;;iBAAsB,oBAAA,CAAqB,QAAA,UAAkB,OAAA,WAAkB,OAAA"}

package/dist/path-guard.mjs

@@ -0,0 +1,35 @@
+import { dirname, resolve } from "node:path";
+import { realpath } from "node:fs/promises";
+import { AFSError } from "@aigne/afs";
+
+//#region src/path-guard.ts
+/**
+* Assert that a resolved path stays within the given root directory.
+* Performs both logical path check and realpath-based symlink check.
+*/
+async function assertPathWithinRoot(fullPath, rootDir) {
+	const mountRoot = resolve(rootDir);
+	const resolved = resolve(fullPath);
+	if (resolved !== mountRoot && !resolved.startsWith(`${mountRoot}/`)) throw new AFSError("Path traversal is not allowed", "AFS_PERMISSION_DENIED");
+	try {
+		let real;
+		try {
+			real = await realpath(resolved);
+		} catch {
+			const parent = dirname(resolved);
+			try {
+				real = await realpath(parent);
+			} catch {
+				return;
+			}
+		}
+		const realMountRoot = await realpath(mountRoot);
+		if (real !== realMountRoot && !real.startsWith(`${realMountRoot}/`)) throw new AFSError("Path traversal via symlink is not allowed", "AFS_PERMISSION_DENIED");
+	} catch (error) {
+		if (error instanceof AFSError) throw error;
+	}
+}
+
+//#endregion
+export { assertPathWithinRoot };
+//# sourceMappingURL=path-guard.mjs.map

package/dist/path-guard.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-guard.mjs","names":[],"sources":["../src/path-guard.ts"],"sourcesContent":["import { realpath } from \"node:fs/promises\";\nimport { dirname, resolve } from \"node:path\";\nimport { AFSError } from \"@aigne/afs\";\n\n/**\n * Assert that a resolved path stays within the given root directory.\n * Performs both logical path check and realpath-based symlink check.\n */\nexport async function assertPathWithinRoot(fullPath: string, rootDir: string): Promise<void> {\n  const mountRoot = resolve(rootDir);\n  const resolved = resolve(fullPath);\n\n  // 1. Logical path check (catches ../ traversal)\n  if (resolved !== mountRoot && !resolved.startsWith(`${mountRoot}/`)) {\n    throw new AFSError(\"Path traversal is not allowed\", \"AFS_PERMISSION_DENIED\");\n  }\n\n  // 2. Symlink-aware check: resolve real path and verify it's still within root\n  try {\n    let real: string;\n    try {\n      real = await realpath(resolved);\n    } catch {\n      // Target doesn't exist yet (e.g. write to new file) — check parent\n      const parent = dirname(resolved);\n      try {\n        real = await realpath(parent);\n      } catch {\n        // Parent also doesn't exist — logical check is sufficient\n        return;\n      }\n    }\n    const realMountRoot = await realpath(mountRoot);\n    if (real !== realMountRoot && !real.startsWith(`${realMountRoot}/`)) {\n      throw new AFSError(\"Path traversal via symlink is not allowed\", \"AFS_PERMISSION_DENIED\");\n    }\n  } catch (error) {\n    if (error instanceof AFSError) throw error;\n    // Other filesystem errors (e.g. permission denied) — let the actual operation handle them\n  }\n}\n"],"mappings":";;;;;;;;;AAQA,eAAsB,qBAAqB,UAAkB,SAAgC;CAC3F,MAAM,YAAY,QAAQ,QAAQ;CAClC,MAAM,WAAW,QAAQ,SAAS;AAGlC,KAAI,aAAa,aAAa,CAAC,SAAS,WAAW,GAAG,UAAU,GAAG,CACjE,OAAM,IAAI,SAAS,iCAAiC,wBAAwB;AAI9E,KAAI;EACF,IAAI;AACJ,MAAI;AACF,UAAO,MAAM,SAAS,SAAS;UACzB;GAEN,MAAM,SAAS,QAAQ,SAAS;AAChC,OAAI;AACF,WAAO,MAAM,SAAS,OAAO;WACvB;AAEN;;;EAGJ,MAAM,gBAAgB,MAAM,SAAS,UAAU;AAC/C,MAAI,SAAS,iBAAiB,CAAC,KAAK,WAAW,GAAG,cAAc,GAAG,CACjE,OAAM,IAAI,SAAS,6CAA6C,wBAAwB;UAEnF,OAAO;AACd,MAAI,iBAAiB,SAAU,OAAM"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@aigne/afs-provider-utils",
+  "version": "1.11.0-beta.12",
+  "description": "Shared utilities for AFS providers: MIME detection, path resolution, path guard",
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "Arcblock <blocklet@arcblock.io> https://github.com/arcblock",
+  "homepage": "https://github.com/arcblock/afs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arcblock/afs"
+  },
+  "bugs": {
+    "url": "https://github.com/arcblock/afs/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.mjs"
+    },
+    "./*": "./*"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "@aigne/afs": "^1.11.0-beta.12"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.6",
+    "npm-run-all": "^4.1.5",
+    "rimraf": "^6.1.2",
+    "tsdown": "0.20.0-beta.3",
+    "typescript": "5.9.2",
+    "@aigne/scripts": "0.0.0",
+    "@aigne/typescript-config": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "check-types": "tsc --noEmit",
+    "clean": "rimraf dist coverage",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage --coverage-reporter=lcov --coverage-reporter=text"
+  }
+}