@flowcodex/core 0.3.0

package/src/utils/image-resize.ts

@@ -0,0 +1,76 @@
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+
+let _photon: {
+  initSync(opts: { module: Buffer }): void;
+  PhotonImage: {
+    new_from_byteslice(data: Uint8Array): PhotonImage;
+  };
+  resize(img: PhotonImage, w: number, h: number, filter: number): PhotonImage;
+} | undefined;
+interface PhotonImage {
+  get_width(): number;
+  get_height(): number;
+  get_bytes_jpeg(quality: number): Uint8Array;
+  free(): void;
+}
+
+function loadPhoton() {
+  if (_photon) return;
+  try {
+    const r = createRequire(import.meta.url);
+    const raw = r('@silvia-odwyer/photon');
+    const wasmPath = r.resolve('@silvia-odwyer/photon/photon_rs_bg.wasm');
+    raw.initSync({ module: readFileSync(wasmPath) });
+    _photon = raw as NonNullable<typeof _photon>;
+  } catch {
+    // photon unavailable — resizeImageBuffer falls back to no-op
+  }
+}
+
+export interface ResizeOptions {
+  maxWidth?: number | undefined;
+  maxHeight?: number | undefined;
+  quality?: number | undefined;
+}
+
+export interface ResizeResult {
+  buffer: Buffer;
+  mediaType: string;
+  resized: boolean;
+}
+
+const DEFAULT_MAX_WIDTH = 1568;
+const DEFAULT_MAX_HEIGHT = 1568;
+const DEFAULT_QUALITY = 85;
+
+export function resizeImageBuffer(input: Buffer, opts?: ResizeOptions): ResizeResult {
+  if (!_photon) loadPhoton();
+  const photon = _photon;
+  if (!photon) return { buffer: input, mediaType: '', resized: false };
+  const maxW = opts?.maxWidth ?? DEFAULT_MAX_WIDTH;
+  const maxH = opts?.maxHeight ?? DEFAULT_MAX_HEIGHT;
+  const quality = opts?.quality ?? DEFAULT_QUALITY;
+
+  const image = photon.PhotonImage.new_from_byteslice(new Uint8Array(input));
+  const width = image.get_width();
+  const height = image.get_height();
+
+  if (width <= maxW && height <= maxH) {
+    image.free();
+    return { buffer: input, mediaType: '', resized: false };
+  }
+
+  const ratio = Math.min(maxW / width, maxH / height);
+  const newW = Math.max(1, Math.round(width * ratio));
+  const newH = Math.max(1, Math.round(height * ratio));
+
+  const resized = photon.resize(image, newW, newH, 1);
+  const outputBytes = resized.get_bytes_jpeg(quality);
+  const outputBuffer = Buffer.from(outputBytes);
+
+  image.free();
+  resized.free();
+
+  return { buffer: outputBuffer, mediaType: 'image/jpeg', resized: true };
+}

package/src/utils/ssrf-guard.ts

@@ -0,0 +1,133 @@
+import type { LookupAddress } from 'node:dns';
+import * as dns from 'node:dns/promises';
+import { ERROR_CODES, FlowCodexError } from '../types/errors.js';
+
+export function isPrivateIp(ip: string): boolean {
+  if (ip.includes(':')) {
+    return isPrivateIpv6(ip.toLowerCase());
+  }
+  return isPrivateIpv4(ip);
+}
+
+function isPrivateIpv4(ip: string): boolean {
+  const parts = ip.split('.');
+  if (parts.length !== 4) return false;
+  const nums = parts.map((p) => Number.parseInt(p, 10));
+  if (nums.some((n) => Number.isNaN(n) || n < 0 || n > 255)) return false;
+  const a = nums[0];
+  const b = nums[1];
+  if (a === undefined || b === undefined) return false;
+  if (a === 10) return true;
+  if (a === 172 && b >= 16 && b <= 31) return true;
+  if (a === 192 && b === 168) return true;
+  if (a === 127) return true;
+  if (a === 169 && b === 254) return true;
+  if (a === 0) return true;
+  return false;
+}
+
+function isPrivateIpv6(ip: string): boolean {
+  if (ip === '::1') return true;
+  if (ip.startsWith('fc') || ip.startsWith('fd')) return true;
+  if (
+    ip.startsWith('fe8') ||
+    ip.startsWith('fe9') ||
+    ip.startsWith('fea') ||
+    ip.startsWith('feb')
+  ) {
+    return true;
+  }
+  return false;
+}
+
+export interface SafeFetchOptions extends RequestInit {
+  maxRedirects?: number | undefined;
+  maxSize?: number | undefined;
+  timeoutMs?: number | undefined;
+}
+
+function isAllowPrivate(): boolean {
+  return process.env.FLOWCODEX_FETCH_ALLOW_PRIVATE === '1';
+}
+
+async function assertSafeHost(parsed: URL): Promise<void> {
+  if (isAllowPrivate()) return;
+  let addresses: LookupAddress[];
+  try {
+    addresses = await dns.lookup(parsed.hostname, { all: true });
+  } catch (err) {
+    throw new FlowCodexError({
+      message: `DNS resolution failed for ${parsed.hostname}: ${err instanceof Error ? err.message : String(err)}`,
+      code: ERROR_CODES.WEBFETCH_FAILED,
+      subsystem: 'general',
+      context: { host: parsed.hostname },
+    });
+  }
+  for (const addr of addresses) {
+    if (isPrivateIp(addr.address)) {
+      throw new FlowCodexError({
+        message: `Blocked: ${parsed.hostname} resolves to private IP ${addr.address}`,
+        code: ERROR_CODES.SSRF_BLOCKED,
+        subsystem: 'general',
+        context: { url: parsed.toString(), ip: addr.address, reason: 'private' },
+      });
+    }
+  }
+}
+
+export async function safeFetch(url: string, opts: SafeFetchOptions = {}): Promise<Response> {
+  const maxRedirects = opts.maxRedirects ?? 5;
+  const timeoutMs = opts.timeoutMs ?? 15_000;
+
+  const fetchOpts: RequestInit = { ...opts };
+  delete (fetchOpts as Partial<SafeFetchOptions>).maxRedirects;
+  delete (fetchOpts as Partial<SafeFetchOptions>).maxSize;
+  delete (fetchOpts as Partial<SafeFetchOptions>).timeoutMs;
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  if (opts.signal) {
+    opts.signal.addEventListener('abort', () => controller.abort());
+  }
+  fetchOpts.signal = controller.signal;
+
+  let currentUrl = url;
+  for (let i = 0; i <= maxRedirects; i++) {
+    const parsed = new URL(currentUrl);
+    await assertSafeHost(parsed);
+
+    let response: Response;
+    try {
+      response = await fetch(currentUrl, { ...fetchOpts, redirect: 'manual' });
+    } catch (err) {
+      clearTimeout(timer);
+      throw new FlowCodexError({
+        message: `Fetch failed: ${err instanceof Error ? err.message : String(err)}`,
+        code: ERROR_CODES.WEBFETCH_FAILED,
+        subsystem: 'general',
+        context: { url: currentUrl },
+        cause: err,
+      });
+    }
+
+    if (response.status >= 300 && response.status < 400) {
+      const location = response.headers.get('location');
+      if (!location) {
+        clearTimeout(timer);
+        return response;
+      }
+      currentUrl = new URL(location, currentUrl).toString();
+      continue;
+    }
+
+    clearTimeout(timer);
+    return response;
+  }
+
+  clearTimeout(timer);
+  throw new FlowCodexError({
+    message: `Too many redirects (max ${maxRedirects})`,
+    code: ERROR_CODES.WEBFETCH_FAILED,
+    subsystem: 'general',
+  });
+}

package/src/utils/ulid.ts

@@ -0,0 +1,72 @@
+const ENCODING = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+const ENCODING_LEN = 32;
+const TIME_LEN = 10;
+const RANDOM_LEN = 16;
+
+import { randomFillSync } from 'node:crypto';
+
+let lastTime = 0;
+let lastRandom: Uint8Array = new Uint8Array(16);
+
+function encodeTime(now: number, len: number): string {
+  let str = '';
+  for (let i = len - 1; i >= 0; i--) {
+    const mod = now % ENCODING_LEN;
+    str = (ENCODING[mod] ?? '0') + str;
+    now = (now - mod) / ENCODING_LEN;
+  }
+  return str;
+}
+
+function encodeRandom(bytes: Uint8Array, len: number): string {
+  let str = '';
+  for (let i = 0; i < len; i++) {
+    const byte = bytes[i] ?? 0;
+    str += ENCODING[byte % ENCODING_LEN] ?? '0';
+  }
+  return str;
+}
+
+export function ulid(now: number = Date.now()): string {
+  if (now <= lastTime) {
+    for (let i = 15; i >= 0; i--) {
+      const val = lastRandom[i] ?? 0;
+      if (val === 0xff) {
+        lastRandom[i] = 0;
+      } else {
+        lastRandom[i] = val + 1;
+        break;
+      }
+    }
+  } else {
+    const buf = new Uint8Array(16);
+    randomFillSync(buf);
+    lastRandom = buf;
+  }
+  lastTime = now;
+  return encodeTime(now, TIME_LEN) + encodeRandom(lastRandom, RANDOM_LEN);
+}
+
+export function ulidTime(ulidStr: string): number {
+  if (ulidStr.length !== TIME_LEN + RANDOM_LEN) {
+    throw new Error(`Invalid ULID length: expected ${TIME_LEN + RANDOM_LEN}, got ${ulidStr.length}`);
+  }
+  const timeChars = ulidStr.slice(0, TIME_LEN);
+  let time = 0;
+  for (let i = 0; i < TIME_LEN; i++) {
+    const ch = timeChars[i] ?? '';
+    const idx = ENCODING.indexOf(ch);
+    if (idx === -1) throw new Error(`Invalid ULID character: ${ch}`);
+    time = time * ENCODING_LEN + idx;
+  }
+  return time;
+}
+
+export function isUlid(str: string): boolean {
+  if (str.length !== TIME_LEN + RANDOM_LEN) return false;
+  for (let i = 0; i < str.length; i++) {
+    const ch = str[i] ?? '';
+    if (ENCODING.indexOf(ch) === -1) return false;
+  }
+  return true;
+}

package/src/utils/version-check.ts

@@ -0,0 +1,59 @@
+export interface VersionInfo {
+  current: string;
+  latest: string;
+  updateAvailable: boolean;
+}
+
+const REGISTRY_URL = 'https://registry.npmjs.org';
+const CHECK_TIMEOUT_MS = 3_000;
+
+export async function fetchLatestVersion(
+  packageName: string,
+  opts?: { fetchImpl?: typeof fetch; registryUrl?: string; timeoutMs?: number },
+): Promise<string | undefined> {
+  const fetchImpl = opts?.fetchImpl ?? fetch;
+  const base = opts?.registryUrl ?? REGISTRY_URL;
+  const timeout = opts?.timeoutMs ?? CHECK_TIMEOUT_MS;
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeout);
+  try {
+    const res = await fetchImpl(`${base}/${packageName}/latest`, {
+      signal: controller.signal,
+    });
+    if (!res.ok) return undefined;
+    const body = (await res.json()) as { version?: string };
+    return body.version;
+  } catch {
+    return undefined;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export function compareVersions(current: string, latest: string): -1 | 0 | 1 {
+  const parse = (v: string): number[] => v.split('.').map(Number);
+  const a = parse(current);
+  const b = parse(latest);
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    const av = a[i] ?? 0;
+    const bv = b[i] ?? 0;
+    if (av < bv) return -1;
+    if (av > bv) return 1;
+  }
+  return 0;
+}
+
+export async function checkForUpdate(
+  currentVersion: string,
+  packageName: string,
+  opts?: { fetchImpl?: typeof fetch; registryUrl?: string },
+): Promise<VersionInfo | undefined> {
+  const latest = await fetchLatestVersion(packageName, opts);
+  if (!latest) return undefined;
+  return {
+    current: currentVersion,
+    latest,
+    updateAvailable: compareVersions(currentVersion, latest) < 0,
+  };
+}