@holo-js/kernel 0.3.26 → 0.3.28

package/dist/file-content.d.ts

@@ -0,0 +1,9 @@
+type FileContentInspection = {
+    readonly mimeType: string | null;
+    readonly passive: boolean;
+};
+declare const fileContentSampleBytes = 65536;
+declare function mimeTypeFromFileName(fileName: string): string | null;
+declare function inspectFileContent(sample: Uint8Array, fileName?: string): Promise<FileContentInspection>;
+
+export { type FileContentInspection, fileContentSampleBytes, inspectFileContent, mimeTypeFromFileName };

package/dist/file-content.mjs

@@ -0,0 +1,54 @@
+// src/fileContent.ts
+var fileContentSampleBytes = 65536;
+var mimeTypesByExtension = Object.freeze({
+  avif: "image/avif",
+  css: "text/css",
+  csv: "text/csv",
+  gif: "image/gif",
+  htm: "text/html",
+  html: "text/html",
+  jpeg: "image/jpeg",
+  jpg: "image/jpeg",
+  json: "application/json",
+  md: "text/markdown",
+  mp3: "audio/mpeg",
+  pdf: "application/pdf",
+  png: "image/png",
+  svg: "image/svg+xml",
+  txt: "text/plain",
+  webp: "image/webp",
+  woff: "font/woff",
+  woff2: "font/woff2",
+  xml: "application/xml"
+});
+var passiveDocumentMimeTypes = /* @__PURE__ */ new Set([
+  "application/json",
+  "application/pdf",
+  "text/css",
+  "text/csv",
+  "text/markdown",
+  "text/plain"
+]);
+function isPassiveMimeType(mimeType) {
+  if (!mimeType) return false;
+  return passiveDocumentMimeTypes.has(mimeType) || /^(?:image|audio|video|font)\//u.test(mimeType) && !mimeType.endsWith("+xml");
+}
+function mimeTypeFromFileName(fileName) {
+  const baseName = fileName.slice(Math.max(fileName.lastIndexOf("/"), fileName.lastIndexOf("\\")) + 1);
+  const separator = baseName.lastIndexOf(".");
+  if (separator < 1) return null;
+  return mimeTypesByExtension[baseName.slice(separator + 1).toLowerCase()] ?? null;
+}
+async function inspectFileContent(sample, fileName) {
+  const { fileTypeFromBuffer, supportedMimeTypes } = await import("file-type");
+  const detectableMimeTypes = supportedMimeTypes;
+  const detected = await fileTypeFromBuffer(sample.subarray(0, fileContentSampleBytes)).catch(() => void 0);
+  const named = fileName ? mimeTypeFromFileName(fileName) : null;
+  const mimeType = detected?.mime ?? (named && !detectableMimeTypes.has(named) ? named : null);
+  return { mimeType, passive: isPassiveMimeType(mimeType) };
+}
+export {
+  fileContentSampleBytes,
+  inspectFileContent,
+  mimeTypeFromFileName
+};

package/dist/image-decoding.browser.d.ts

@@ -0,0 +1,3 @@
+declare function verifyDecodedImage(_contents: Uint8Array, _mimeType: string): Promise<boolean>;
+
+export { verifyDecodedImage };

package/dist/image-decoding.browser.mjs

@@ -0,0 +1,7 @@
+// src/imageDecoding.browser.ts
+async function verifyDecodedImage(_contents, _mimeType) {
+  return true;
+}
+export {
+  verifyDecodedImage
+};

package/dist/image-decoding.d.ts

@@ -0,0 +1,3 @@
+declare function verifyDecodedImage(_contents: Uint8Array, _mimeType: string): Promise<boolean>;
+
+export { verifyDecodedImage };

package/dist/image-decoding.mjs

@@ -0,0 +1,7 @@
+// src/imageDecoding.ts
+async function verifyDecodedImage(_contents, _mimeType) {
+  throw new Error("[@holo-js/kernel] Server-side image validation must run on Node.js, where images can be fully decoded.");
+}
+export {
+  verifyDecodedImage
+};

package/dist/image-decoding.node.d.ts

@@ -0,0 +1,3 @@
+declare function verifyDecodedImage(contents: Uint8Array, mimeType: string): Promise<boolean>;
+
+export { verifyDecodedImage };

package/dist/image-decoding.node.mjs

@@ -0,0 +1,70 @@
+// src/imageDecoding.node.ts
+var maximumDecodedPixels = 4e7;
+var maximumFrames = 1e3;
+var decodedFormatMatchers = Object.freeze({
+  "image/avif": (metadata) => metadata.format === "heif" && metadata.compression === "av1",
+  "image/gif": (metadata) => metadata.format === "gif",
+  "image/jpeg": (metadata) => metadata.format === "jpeg",
+  "image/png": (metadata) => metadata.format === "png",
+  "image/tiff": (metadata) => metadata.format === "tiff",
+  "image/webp": (metadata) => metadata.format === "webp"
+});
+function isMissingModule(error) {
+  if (!(error instanceof Error)) return false;
+  const code = error.code;
+  return code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND" || isMissingModule(error.cause);
+}
+async function loadSharp() {
+  try {
+    return (await import("sharp")).default;
+  } catch (error) {
+    if (!isMissingModule(error)) throw error;
+    throw new Error('[@holo-js/kernel] Server-side image validation requires the optional "sharp" package. Install sharp in your application.', { cause: error });
+  }
+}
+function skipSubBlocks(bytes, start) {
+  let offset = start;
+  while (offset < bytes.length) {
+    const size = bytes[offset] ?? 0;
+    offset += 1;
+    if (size === 0) return offset;
+    offset += size;
+  }
+  return null;
+}
+function colorTableBytes(flags) {
+  return (flags & 128) === 0 ? 0 : 3 * (1 << (flags & 7) + 1);
+}
+function hasCompleteGifStructure(bytes) {
+  let offset = 13 + colorTableBytes(bytes[10] ?? 0);
+  while (offset !== null && offset < bytes.length) {
+    const introducer = bytes[offset];
+    if (introducer === 59) return true;
+    if (introducer === 33) {
+      offset = skipSubBlocks(bytes, offset + 2);
+    } else if (introducer === 44) {
+      offset = skipSubBlocks(bytes, offset + 10 + colorTableBytes(bytes[offset + 9] ?? 0) + 1);
+    } else {
+      return false;
+    }
+  }
+  return false;
+}
+async function verifyDecodedImage(contents, mimeType) {
+  const matchesDecodedFormat = decodedFormatMatchers[mimeType];
+  if (!matchesDecodedFormat) return false;
+  if (mimeType === "image/gif" && !hasCompleteGifStructure(contents)) return false;
+  const decode = await loadSharp();
+  try {
+    const image = decode(contents, { animated: true, failOn: "warning", limitInputPixels: maximumDecodedPixels });
+    const metadata = await image.metadata();
+    if (!matchesDecodedFormat(metadata) || (metadata.pages ?? 1) > maximumFrames) return false;
+    await image.stats();
+    return true;
+  } catch {
+    return false;
+  }
+}
+export {
+  verifyDecodedImage
+};

package/dist/index.d.ts

@@ -409,4 +409,37 @@ declare function resolveNormalizedRedisConnection(config: NormalizedHoloRedisCon
 declare function normalizeRedisConfig(config?: HoloRedisConfig): NormalizedHoloRedisConfig;
 declare function defineRedisConfig<TConfig extends HoloRedisConfig>(config: TConfig): Readonly<TConfig>;
 
-export { type ConcurrencyOptions, DEFAULT_HOLO_PROJECT_PATHS, DEFAULT_REDIS_CONNECTION, DEFAULT_REDIS_DB, DEFAULT_REDIS_HOST, DEFAULT_REDIS_PORT, type DatabaseLogger, HOLO_PROJECT_PREPARE_API_VERSION, type HoloDatabaseDriver, type HoloGeneratedProjectArtifact, type HoloManagedProjectArtifact, type HoloPluginBroadcastContributions, type HoloPluginCacheContributions, type HoloPluginCliContributions, type HoloPluginConfigContributions, type HoloPluginContributions, type HoloPluginDefinition, type HoloPluginDependencyContributions, type HoloPluginFrameworkContribution, type HoloPluginFrameworkTsconfigKind, type HoloPluginMailContributions, type HoloPluginMigrationContributions, type HoloPluginNotificationContributions, type HoloPluginPackageManager, type HoloPluginProjectContributions, type HoloPluginQueueContributions, type HoloPluginRuntimeContributions, type HoloPluginRuntimeMapContributions, type HoloPluginRuntimeModule, type HoloProjectArtifactContents, type HoloProjectConfig, type HoloProjectConnectionConfig, type HoloProjectDatabaseConfig, type HoloProjectPaths, type HoloProjectPrepareChange, type HoloProjectPrepareChangeKind, type HoloProjectPrepareCommand, type HoloProjectPrepareContext, type HoloProjectPrepareDiagnostic, HoloProjectPrepareError, type HoloProjectPrepareFailure, type HoloProjectPrepareFramework, type HoloProjectPrepareFullRetry, type HoloProjectPrepareLogger, type HoloProjectPrepareModule, type HoloProjectPreparePlugin, type HoloProjectPrepareResult, type HoloProjectPrepareRun, type HoloProjectPrepareSource, type HoloProjectPrepareWatch, type HoloProjectPreparedResult, type HoloProjectPreparer, type HoloRedisClusterNodeConfig, type HoloRedisConfig, type HoloRedisConnectionConfig, type LoadedHoloPluginDefinition, type MigrationErrorLog, type MigrationStartLog, type MigrationSuccessLog, type NormalizedHoloProjectConfig, type NormalizedHoloRedisClusterNodeConfig, type NormalizedHoloRedisConfig, type NormalizedHoloRedisConnectionConfig, type PluginLoadOptions, type QueryErrorLog, type QueryStartLog, type QuerySuccessLog, type RuntimeContribution, RuntimeLifecycle, type RuntimeLifecycleContext, type SeederErrorLog, type SeederStartLog, type SeederSuccessLog, type TransactionLog, type TransactionScopeKind, createRuntimeLifecycle, defineHoloPlugin, defineHoloProject, defineHoloProjectPreparer, defineRedisConfig, holoRedisDefaults, loadHoloPluginBootModules, loadHoloPluginContributionModules, loadHoloPluginDefinitions, normalizeHoloPluginDefinition, normalizeHoloProjectConfig, normalizeRedisConfig, resolveHoloPluginModulePath, resolveNormalizedRedisConnection };
+type HoloRequestHeaders = Headers | ReadonlyArray<readonly [string, string]> | Record<string, string | readonly string[] | undefined> | {
+    readonly get?: (name: string) => string | null | undefined;
+    readonly forEach?: (callback: (value: string, key: string) => void) => void;
+    readonly entries?: () => Iterable<readonly [string, string]>;
+};
+type RequestUrlParts = {
+    readonly url?: string | URL;
+    readonly path?: string;
+    readonly headers?: HoloRequestHeaders;
+};
+type HoloRequestInput = RequestUrlParts & {
+    readonly request?: Request;
+    readonly req?: RequestUrlParts;
+    readonly node?: {
+        readonly req?: RequestUrlParts;
+    };
+    readonly web?: {
+        readonly request?: RequestUrlParts;
+    };
+};
+type HoloTrustedProxyHeaders = 'x-forwarded' | 'forwarded';
+declare function resolveTrustedProxyHeaders(): HoloTrustedProxyHeaders | null;
+declare function readForwardedParameter(headers: HoloRequestHeaders | undefined, name: string): string | undefined;
+declare class HoloRequestUrlError extends TypeError {
+    readonly status = 400;
+    constructor(message: string);
+}
+declare function resolveRequestUrl(input: HoloRequestInput): URL;
+declare const requestUrlInternals: Readonly<{
+    readForwardedParameter: typeof readForwardedParameter;
+    resolveTrustedProxyHeaders: typeof resolveTrustedProxyHeaders;
+}>;
+
+export { type ConcurrencyOptions, DEFAULT_HOLO_PROJECT_PATHS, DEFAULT_REDIS_CONNECTION, DEFAULT_REDIS_DB, DEFAULT_REDIS_HOST, DEFAULT_REDIS_PORT, type DatabaseLogger, HOLO_PROJECT_PREPARE_API_VERSION, type HoloDatabaseDriver, type HoloGeneratedProjectArtifact, type HoloManagedProjectArtifact, type HoloPluginBroadcastContributions, type HoloPluginCacheContributions, type HoloPluginCliContributions, type HoloPluginConfigContributions, type HoloPluginContributions, type HoloPluginDefinition, type HoloPluginDependencyContributions, type HoloPluginFrameworkContribution, type HoloPluginFrameworkTsconfigKind, type HoloPluginMailContributions, type HoloPluginMigrationContributions, type HoloPluginNotificationContributions, type HoloPluginPackageManager, type HoloPluginProjectContributions, type HoloPluginQueueContributions, type HoloPluginRuntimeContributions, type HoloPluginRuntimeMapContributions, type HoloPluginRuntimeModule, type HoloProjectArtifactContents, type HoloProjectConfig, type HoloProjectConnectionConfig, type HoloProjectDatabaseConfig, type HoloProjectPaths, type HoloProjectPrepareChange, type HoloProjectPrepareChangeKind, type HoloProjectPrepareCommand, type HoloProjectPrepareContext, type HoloProjectPrepareDiagnostic, HoloProjectPrepareError, type HoloProjectPrepareFailure, type HoloProjectPrepareFramework, type HoloProjectPrepareFullRetry, type HoloProjectPrepareLogger, type HoloProjectPrepareModule, type HoloProjectPreparePlugin, type HoloProjectPrepareResult, type HoloProjectPrepareRun, type HoloProjectPrepareSource, type HoloProjectPrepareWatch, type HoloProjectPreparedResult, type HoloProjectPreparer, type HoloRedisClusterNodeConfig, type HoloRedisConfig, type HoloRedisConnectionConfig, type HoloRequestHeaders, type HoloRequestInput, HoloRequestUrlError, type HoloTrustedProxyHeaders, type LoadedHoloPluginDefinition, type MigrationErrorLog, type MigrationStartLog, type MigrationSuccessLog, type NormalizedHoloProjectConfig, type NormalizedHoloRedisClusterNodeConfig, type NormalizedHoloRedisConfig, type NormalizedHoloRedisConnectionConfig, type PluginLoadOptions, type QueryErrorLog, type QueryStartLog, type QuerySuccessLog, type RuntimeContribution, RuntimeLifecycle, type RuntimeLifecycleContext, type SeederErrorLog, type SeederStartLog, type SeederSuccessLog, type TransactionLog, type TransactionScopeKind, createRuntimeLifecycle, defineHoloPlugin, defineHoloProject, defineHoloProjectPreparer, defineRedisConfig, holoRedisDefaults, loadHoloPluginBootModules, loadHoloPluginContributionModules, loadHoloPluginDefinitions, normalizeHoloPluginDefinition, normalizeHoloProjectConfig, normalizeRedisConfig, requestUrlInternals, resolveHoloPluginModulePath, resolveNormalizedRedisConnection, resolveRequestUrl };

package/dist/index.mjs

@@ -426,6 +426,134 @@ function normalizeRedisConfig(config = {}) {
 function defineRedisConfig(config) {
   return Object.freeze({ ...config });
 }
+
+// src/requestUrl.ts
+function resolveTrustedProxyHeaders() {
+  const value = typeof process === "undefined" ? void 0 : process.env.HOLO_SECURITY_TRUST_PROXY?.trim().toLowerCase();
+  if (value === "forwarded") return "forwarded";
+  if (value === "x-forwarded" || value === "1" || value === "true" || value === "yes" || value === "on") return "x-forwarded";
+  return null;
+}
+function isHeaderTuples(headers) {
+  return Array.isArray(headers);
+}
+function readHeader(headers, name) {
+  if (!headers) return void 0;
+  if (isHeaderTuples(headers)) {
+    return headers.find(([key]) => key.toLowerCase() === name)?.[1];
+  }
+  if ("get" in headers && typeof headers.get === "function") return headers.get(name) ?? void 0;
+  if ("entries" in headers && typeof headers.entries === "function") {
+    for (const [key, value] of headers.entries()) {
+      if (key.toLowerCase() === name) return value;
+    }
+    return void 0;
+  }
+  if ("forEach" in headers && typeof headers.forEach === "function") {
+    let result;
+    headers.forEach((value, key) => {
+      if (key.toLowerCase() === name) result = value;
+    });
+    return result;
+  }
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() === name) {
+      return typeof value === "string" ? value : Array.isArray(value) ? value.join(",") : void 0;
+    }
+  }
+  return void 0;
+}
+function firstForwardedValue(value) {
+  return value?.split(",", 1)[0]?.trim().replace(/^"|"$/g, "");
+}
+function firstForwardedElement(value) {
+  const pairs = /* @__PURE__ */ new Map();
+  let key = "";
+  let current = "";
+  let readingValue = false;
+  let quoted = false;
+  let escaped = false;
+  const commit = () => {
+    const name = key.trim().toLowerCase();
+    if (readingValue && name && !pairs.has(name)) pairs.set(name, current.trim());
+    key = "";
+    current = "";
+    readingValue = false;
+  };
+  for (const character of value) {
+    if (escaped) {
+      current += character;
+      escaped = false;
+    } else if (quoted) {
+      if (character === "\\") escaped = true;
+      else if (character === '"') quoted = false;
+      else current += character;
+    } else if (character === ",") {
+      break;
+    } else if (character === ";") {
+      commit();
+    } else if (character === "=" && !readingValue) {
+      readingValue = true;
+    } else if (character === '"' && readingValue) {
+      quoted = true;
+    } else if (readingValue) {
+      current += character;
+    } else {
+      key += character;
+    }
+  }
+  commit();
+  return pairs;
+}
+function readForwardedParameter(headers, name) {
+  const forwarded = readHeader(headers, "forwarded");
+  return forwarded === void 0 ? void 0 : firstForwardedElement(forwarded).get(name);
+}
+function readTrustedProxyValue(headers, trustedProxyHeaders, name) {
+  if (trustedProxyHeaders === "forwarded") return readForwardedParameter(headers, name);
+  if (trustedProxyHeaders === "x-forwarded") return firstForwardedValue(readHeader(headers, `x-forwarded-${name}`));
+  return void 0;
+}
+var HoloRequestUrlError = class extends TypeError {
+  status = 400;
+  constructor(message) {
+    super(`[@holo-js/kernel] ${message}`);
+    this.name = "HoloRequestUrlError";
+  }
+};
+var invalidRequestHostMessage = "Request hosts must be a valid hostname and optional port.";
+function parseRequestUrl(value, invalidMessage) {
+  if (!URL.canParse(String(value), "http://localhost")) throw new HoloRequestUrlError(invalidMessage);
+  return new URL(value, "http://localhost");
+}
+function resolveRequestUrl(input) {
+  const nested = input instanceof Request ? void 0 : input.request ?? input.web?.request ?? input.req ?? input.node?.req;
+  const headers = input.headers ?? nested?.headers;
+  const value = input.url ?? nested?.url ?? input.path ?? (nested && "path" in nested ? nested.path : void 0) ?? "/";
+  const invalidUrlMessage = "Request URLs must use http or https without credentials.";
+  const url = parseRequestUrl(value, invalidUrlMessage);
+  if (url.username || url.password || url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new HoloRequestUrlError(invalidUrlMessage);
+  }
+  const trustedProxyHeaders = resolveTrustedProxyHeaders();
+  const protocol = (readTrustedProxyValue(headers, trustedProxyHeaders, "proto") ?? url.protocol.slice(0, -1)).toLowerCase();
+  if (protocol !== "http" && protocol !== "https") {
+    throw new HoloRequestUrlError("Request protocols must be http or https.");
+  }
+  const host = readTrustedProxyValue(headers, trustedProxyHeaders, "host") ?? readHeader(headers, "host") ?? url.host;
+  if (!host || /[\s,/@\\?#]/u.test(host)) {
+    throw new HoloRequestUrlError(invalidRequestHostMessage);
+  }
+  const origin = parseRequestUrl(`${protocol}://${host}`, invalidRequestHostMessage);
+  if (origin.pathname !== "/" || origin.username || origin.password || origin.search || origin.hash) {
+    throw new HoloRequestUrlError(invalidRequestHostMessage);
+  }
+  url.protocol = origin.protocol;
+  url.host = origin.host;
+  url.port = origin.port;
+  return url;
+}
+var requestUrlInternals = Object.freeze({ readForwardedParameter, resolveTrustedProxyHeaders });
 export {
   DEFAULT_HOLO_PROJECT_PATHS,
   DEFAULT_REDIS_CONNECTION,
@@ -434,6 +562,7 @@ export {
   DEFAULT_REDIS_PORT,
   HOLO_PROJECT_PREPARE_API_VERSION,
   HoloProjectPrepareError,
+  HoloRequestUrlError,
   RuntimeLifecycle,
   createRuntimeLifecycle,
   defineHoloPlugin,
@@ -449,6 +578,8 @@ export {
   normalizeHoloPluginDefinition,
   normalizeHoloProjectConfig,
   normalizeRedisConfig,
+  requestUrlInternals,
   resolveHoloPluginModulePath,
-  resolveNormalizedRedisConnection
+  resolveNormalizedRedisConnection,
+  resolveRequestUrl
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holo-js/kernel",
-  "version": "0.3.26",
+  "version": "0.3.28",
   "description": "Holo-JS Framework - dependency-free contracts, plugins, and runtime lifecycle",
   "type": "module",
   "license": "MIT",
@@ -14,6 +14,17 @@
       "types": "./dist/http-errors.d.ts",
       "import": "./dist/http-errors.mjs",
       "default": "./dist/http-errors.mjs"
+    },
+    "./file-content": {
+      "types": "./dist/file-content.d.ts",
+      "import": "./dist/file-content.mjs",
+      "default": "./dist/file-content.mjs"
+    },
+    "./image-decoding": {
+      "types": "./dist/image-decoding.d.ts",
+      "browser": "./dist/image-decoding.browser.mjs",
+      "node": "./dist/image-decoding.node.mjs",
+      "default": "./dist/image-decoding.mjs"
     }
   },
   "main": "./dist/index.mjs",
@@ -29,11 +40,25 @@
   },
   "devDependencies": {
     "@types/node": "^22.10.2",
+    "file-type": "^22.2.0",
+    "sharp": "^0.35.4",
     "tsup": "^8.3.5",
     "typescript": "^5.7.2",
     "vitest": "^4.1.5"
   },
   "engines": {
     "node": "^22.12.0 || ^24.0.0 || ^26.0.0"
+  },
+  "peerDependencies": {
+    "file-type": "^22.2.0",
+    "sharp": "^0.35.4"
+  },
+  "peerDependenciesMeta": {
+    "file-type": {
+      "optional": true
+    },
+    "sharp": {
+      "optional": true
+    }
   }
 }