@gmickel/gno 1.32.0 → 1.34.0

package/src/publish/attachment-discover.ts

@@ -0,0 +1,203 @@
+/** CommonMark + Obsidian image discovery for publish attachments. */
+
+import { fromMarkdown } from "mdast-util-from-markdown";
+import { gfmFromMarkdown } from "mdast-util-gfm";
+import { gfm } from "micromark-extension-gfm";
+
+import {
+  type ExcludedRange,
+  getExcludedRanges,
+  rangeIntersectsExcluded,
+} from "../ingestion/strip";
+import { parseObsidianEmbedAt } from "./attachment-obsidian";
+
+export interface DiscoveredImageRef {
+  alt: string;
+  end: number;
+  kind: "markdown" | "obsidian";
+  sourceRef: string;
+  start: number;
+  title?: string | null;
+}
+
+export interface DiscoverImageOptions {
+  excludeFrontmatter?: boolean;
+}
+
+interface PositionedNode {
+  alt?: string | null;
+  children?: PositionedNode[];
+  identifier?: string;
+  position?: {
+    end: { offset?: number };
+    start: { offset?: number };
+  };
+  type: string;
+  title?: string | null;
+  url?: string;
+}
+
+interface MarkdownScan {
+  definitions: Map<string, { title: string | null; url: string }>;
+  excluded: ExcludedRange[];
+  images: DiscoveredImageRef[];
+  references: PositionedNode[];
+}
+
+const nodeOffsets = (
+  node: PositionedNode
+): { end: number; start: number } | null => {
+  const start = node.position?.start.offset;
+  const end = node.position?.end.offset;
+  return start === undefined || end === undefined ? null : { start, end };
+};
+
+const markdownImage = (
+  node: PositionedNode,
+  sourceRef: string,
+  title: string | null
+): DiscoveredImageRef | null => {
+  const offsets = nodeOffsets(node);
+  if (!offsets) return null;
+  return {
+    alt: node.alt ?? "",
+    end: offsets.end,
+    kind: "markdown",
+    sourceRef,
+    start: offsets.start,
+    title,
+  };
+};
+
+const scanMarkdownAst = (markdown: string): MarkdownScan => {
+  const root = fromMarkdown(markdown, {
+    extensions: [gfm()],
+    mdastExtensions: [gfmFromMarkdown()],
+  }) as PositionedNode;
+  const scan: MarkdownScan = {
+    definitions: new Map(),
+    excluded: [],
+    images: [],
+    references: [],
+  };
+
+  const visit = (node: PositionedNode): void => {
+    const offsets = nodeOffsets(node);
+    if (
+      offsets &&
+      (node.type === "code" ||
+        node.type === "inlineCode" ||
+        node.type === "html" ||
+        node.type === "definition")
+    ) {
+      scan.excluded.push({ ...offsets, kind: "inline_code" });
+    }
+    if (offsets && node.type === "link") {
+      const isAutolink =
+        markdown[offsets.start] === "<" && markdown[offsets.end - 1] === ">";
+      const childEnds = (node.children ?? [])
+        .map((child) => nodeOffsets(child)?.end)
+        .filter((offset): offset is number => offset !== undefined);
+      scan.excluded.push({
+        start: isAutolink
+          ? offsets.start
+          : childEnds.length === 0
+            ? offsets.start
+            : Math.max(...childEnds),
+        end: offsets.end,
+        kind: "inline_code",
+      });
+    }
+    if (
+      node.type === "definition" &&
+      node.identifier !== undefined &&
+      node.url !== undefined &&
+      !scan.definitions.has(node.identifier)
+    ) {
+      scan.definitions.set(node.identifier, {
+        title: node.title ?? null,
+        url: node.url,
+      });
+    } else if (node.type === "image" && node.url !== undefined) {
+      const image = markdownImage(node, node.url, node.title ?? null);
+      if (image) scan.images.push(image);
+    } else if (node.type === "imageReference") {
+      scan.references.push(node);
+    }
+    for (const child of node.children ?? []) visit(child);
+  };
+  visit(root);
+
+  for (const reference of scan.references) {
+    const definition = scan.definitions.get(reference.identifier ?? "");
+    if (definition === undefined) continue;
+    const image = markdownImage(reference, definition.url, definition.title);
+    if (image) scan.images.push(image);
+  }
+  return scan;
+};
+
+const isEscapedMarker = (text: string, index: number): boolean => {
+  let backslashes = 0;
+  for (
+    let cursor = index - 1;
+    cursor >= 0 && text[cursor] === "\\";
+    cursor -= 1
+  ) {
+    backslashes += 1;
+  }
+  return backslashes % 2 === 1;
+};
+
+const discoverObsidianImages = (
+  markdown: string,
+  excluded: ExcludedRange[]
+): DiscoveredImageRef[] => {
+  const images: DiscoveredImageRef[] = [];
+  let cursor = 0;
+  while (cursor < markdown.length) {
+    const bang = markdown.indexOf("![[", cursor);
+    if (bang < 0) break;
+    const parsed = isEscapedMarker(markdown, bang)
+      ? null
+      : parseObsidianEmbedAt(markdown, bang);
+    if (
+      parsed &&
+      !rangeIntersectsExcluded(parsed.start, parsed.end, excluded)
+    ) {
+      images.push(parsed);
+    }
+    cursor = parsed?.end ?? bang + 1;
+  }
+  return images;
+};
+
+export const discoverImageOccurrences = (
+  markdown: string,
+  options: DiscoverImageOptions = {}
+): DiscoveredImageRef[] => {
+  const scan = scanMarkdownAst(markdown);
+  const frontmatter =
+    options.excludeFrontmatter === false
+      ? []
+      : getExcludedRanges(markdown).filter(
+          (range) => range.kind === "frontmatter"
+        );
+  const markdownImageRanges: ExcludedRange[] = scan.images.map((image) => ({
+    start: image.start,
+    end: image.end,
+    kind: "inline_code",
+  }));
+  const excluded = [
+    ...scan.excluded,
+    ...frontmatter,
+    ...markdownImageRanges,
+  ].sort((left, right) => left.start - right.start);
+  const markdownImages = scan.images.filter(
+    (image) => !rangeIntersectsExcluded(image.start, image.end, frontmatter)
+  );
+  return [
+    ...markdownImages,
+    ...discoverObsidianImages(markdown, excluded),
+  ].sort((left, right) => left.start - right.start || left.end - right.end);
+};

package/src/publish/attachment-load.ts

@@ -0,0 +1,133 @@
+/**
+ * Load and validate attachment bytes into pending publish asset payloads.
+ *
+ * @module src/publish/attachment-load
+ */
+
+import type {
+  AttachmentDiagnostic,
+  PendingAssetPayload,
+} from "./attachment-types";
+
+import { encodeBytesToBase64, sha256BytesHex } from "./artifact-asset-codec";
+import { MAX_PUBLISH_UPLOAD_BYTES } from "./artifact-asset-contract";
+import { diagnostic, extensionOf } from "./attachment-path";
+import {
+  RASTER_HEADER_PROBE_BYTES,
+  validateRasterBytesStructural,
+  validateRasterDecodable,
+} from "./attachment-raster";
+
+const SUPPORTED_EXT = new Set([
+  ".png",
+  ".jpg",
+  ".jpeg",
+  ".gif",
+  ".webp",
+  ".avif",
+]);
+const UNSUPPORTED_EXT = new Set([".svg", ".pdf", ".html", ".htm"]);
+
+export async function readAndValidateAsset(
+  absPath: string,
+  noteSlug: string,
+  sourceRef: string,
+  relPath: string
+): Promise<PendingAssetPayload | AttachmentDiagnostic> {
+  const ext = extensionOf(relPath);
+  if (UNSUPPORTED_EXT.has(ext)) {
+    return diagnostic(
+      "ASSET_UNSUPPORTED_FORMAT",
+      `Unsupported attachment format "${ext}"`,
+      noteSlug,
+      sourceRef
+    );
+  }
+  const file = Bun.file(absPath);
+  if (!(await file.exists())) {
+    return diagnostic(
+      "ASSET_MISSING",
+      `Attachment not found: ${relPath}`,
+      noteSlug,
+      sourceRef
+    );
+  }
+  const size = file.size;
+  if (size <= 0) {
+    return diagnostic(
+      "ASSET_CORRUPT",
+      "Attachment is empty",
+      noteSlug,
+      sourceRef
+    );
+  }
+  if (size > MAX_PUBLISH_UPLOAD_BYTES) {
+    return diagnostic(
+      "ASSET_OVERSIZE",
+      `Attachment is ${size} bytes before read; max is ${MAX_PUBLISH_UPLOAD_BYTES}`,
+      noteSlug,
+      sourceRef
+    );
+  }
+
+  const header = new Uint8Array(
+    await file.slice(0, Math.min(size, RASTER_HEADER_PROBE_BYTES)).arrayBuffer()
+  );
+  // Header probe uses structural checks only (sync, cheap reject).
+  const headerCheck = validateRasterBytesStructural(header);
+  if (!headerCheck.ok) {
+    const rejectEarly =
+      headerCheck.code === "ASSET_DIMENSION_INVALID" ||
+      headerCheck.code === "ASSET_UNSUPPORTED_FORMAT" ||
+      (headerCheck.code === "ASSET_CORRUPT" &&
+        size <= RASTER_HEADER_PROBE_BYTES);
+    if (rejectEarly) {
+      if (
+        headerCheck.code === "ASSET_UNSUPPORTED_FORMAT" &&
+        SUPPORTED_EXT.has(ext)
+      ) {
+        return diagnostic(
+          "ASSET_MIME_SPOOF",
+          `Extension ${ext} does not match raster bytes`,
+          noteSlug,
+          sourceRef
+        );
+      }
+      return diagnostic(
+        headerCheck.code,
+        headerCheck.message,
+        noteSlug,
+        sourceRef
+      );
+    }
+  }
+
+  const bytes = new Uint8Array(await file.arrayBuffer());
+  // Full producer path: structural validation plus pixel decodability before bundling.
+  const validated = await validateRasterDecodable(bytes);
+  if (!validated.ok) {
+    if (
+      validated.code === "ASSET_UNSUPPORTED_FORMAT" &&
+      SUPPORTED_EXT.has(ext)
+    ) {
+      return diagnostic(
+        "ASSET_MIME_SPOOF",
+        `Extension ${ext} does not match raster bytes`,
+        noteSlug,
+        sourceRef
+      );
+    }
+    return diagnostic(validated.code, validated.message, noteSlug, sourceRef);
+  }
+
+  const sha256 = sha256BytesHex(bytes);
+  return {
+    byteLength: bytes.byteLength,
+    data: encodeBytesToBase64(bytes),
+    height: validated.height,
+    mediaType: validated.mediaType,
+    references: [{ noteSlug, sourceRef: relPath }],
+    sha256,
+    width: validated.width,
+  };
+}

package/src/publish/attachment-obsidian.ts

@@ -0,0 +1,45 @@
+/** Obsidian image-embed parsing for publish attachment discovery. */
+
+import type { DiscoveredImageRef } from "./attachment-discover";
+
+const parseObsidianTarget = (
+  raw: string
+): { alias: string; pathPart: string } => {
+  // Markdown tables require Obsidian's separator pipes to be escaped. Restore
+  // those escapes before applying Obsidian's target|alias grammar.
+  const normalized = raw.replaceAll("\\|", "|");
+  const pipe = normalized.indexOf("|");
+  const pathWithFrag = pipe >= 0 ? normalized.slice(0, pipe) : normalized;
+  const alias = pipe >= 0 ? normalized.slice(pipe + 1).trim() : "";
+  const hash = pathWithFrag.indexOf("#");
+  const pathPart = (
+    hash >= 0 ? pathWithFrag.slice(0, hash) : pathWithFrag
+  ).trim();
+  return { alias, pathPart };
+};
+
+export const parseObsidianEmbedAt = (
+  text: string,
+  bangIndex: number
+): DiscoveredImageRef | null => {
+  if (text.slice(bangIndex, bangIndex + 3) !== "![[") return null;
+  let i = bangIndex + 3;
+  let raw = "";
+  while (i < text.length) {
+    const ch = text[i] ?? "";
+    if (ch === "]" && text[i + 1] === "]") {
+      const parsed = parseObsidianTarget(raw);
+      return {
+        alt: parsed.alias,
+        end: i + 2,
+        kind: "obsidian",
+        sourceRef: parsed.pathPart,
+        start: bangIndex,
+      };
+    }
+    if (ch === "\n" || ch === "\r") return null;
+    raw += ch;
+    i += 1;
+  }
+  return null;
+};

package/src/publish/attachment-path.ts

@@ -0,0 +1,334 @@
+/**
+ * Collection-root path confinement and basename lookup for publish attachments.
+ *
+ * @module src/publish/attachment-path
+ */
+
+// node:fs/promises realpath/lstat/opendir — no Bun equivalents for symlink-safe identity or prunable directory walking
+import { lstat, opendir, realpath } from "node:fs/promises";
+// node:path — no Bun path utils
+import {
+  isAbsolute,
+  join,
+  normalize,
+  posix as pathPosix,
+  relative,
+  sep,
+} from "node:path";
+
+import type { AttachmentDiagnostic } from "./attachment-types";
+
+import { matchesCollectionExclusion } from "../core/path-rules";
+import { isCanonicalPathContained } from "../core/validation";
+
+const compareCodeUnits = (left: string, right: string): number => {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+};
+
+const isPrivateAttachmentRelPath = (relPath: string): boolean =>
+  relPath.split("/").some((segment) => segment.toLowerCase() === "_internal");
+
+export const diagnostic = (
+  code: AttachmentDiagnostic["code"],
+  message: string,
+  noteSlug: string,
+  sourceRef: string
+): AttachmentDiagnostic => ({ code, message, noteSlug, sourceRef });
+
+export const safePercentDecode = (value: string): string | null => {
+  let current = value;
+  for (let round = 0; round < 4; round += 1) {
+    if (!/%[0-9a-fA-F]{2}/u.test(current)) return current;
+    try {
+      const decoded = decodeURIComponent(current);
+      if (decoded === current) return current;
+      if (decoded.includes("\0")) return null;
+      current = decoded;
+    } catch {
+      return null;
+    }
+  }
+  return current;
+};
+
+const percentDecodeOnce = (value: string): string | null => {
+  if (!/%[0-9a-fA-F]{2}/u.test(value)) return value;
+  try {
+    const decoded = decodeURIComponent(value);
+    return decoded.includes("\0") ? null : decoded;
+  } catch {
+    return null;
+  }
+};
+
+export const extensionOf = (relPath: string): string => {
+  const base = pathPosix.basename(relPath);
+  const dot = base.lastIndexOf(".");
+  if (dot <= 0) return "";
+  return base.slice(dot).toLowerCase();
+};
+
+/**
+ * Build basename → relPath[] index for files under root.
+ *
+ * Unsupported files must remain discoverable so the resolver can report a
+ * stable unsupported-format diagnostic instead of misclassifying them as
+ * missing. Byte validation still decides whether any match may be bundled.
+ */
+export async function buildAttachmentBasenameIndex(
+  collectionRoot: string,
+  collectionExcludes: readonly string[] = []
+): Promise<Map<string, string[]>> {
+  let rootReal: string;
+  try {
+    rootReal = await realpath(normalize(collectionRoot));
+  } catch {
+    return new Map();
+  }
+  const index = new Map<string, string[]>();
+  const walk = async (absDir: string, relDir: string): Promise<void> => {
+    let directory: Awaited<ReturnType<typeof opendir>>;
+    try {
+      directory = await opendir(absDir);
+    } catch {
+      return;
+    }
+    for await (const entry of directory) {
+      const rel = relDir ? `${relDir}/${entry.name}` : entry.name;
+      const excluded =
+        matchesCollectionExclusion(rel, collectionExcludes) ||
+        (entry.isDirectory() &&
+          matchesCollectionExclusion(`${rel}/`, collectionExcludes));
+      if (isPrivateAttachmentRelPath(rel) || excluded) {
+        continue;
+      }
+      if (entry.isDirectory()) {
+        await walk(join(absDir, entry.name), rel);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      const base = pathPosix.basename(rel);
+      const bucket = index.get(base) ?? [];
+      bucket.push(rel);
+      index.set(base, bucket);
+    }
+  };
+  await walk(rootReal, "");
+  for (const [key, values] of index) {
+    index.set(key, [...new Set(values)].sort(compareCodeUnits));
+  }
+  return index;
+}
+
+export interface AttachmentPathContext {
+  basenameIndex: Map<string, string[]>;
+  collectionExcludes?: readonly string[];
+  noteSlug: string;
+  sourceRelPath: string;
+}
+
+const stripMarkdownUrlSuffix = (sourceRef: string): string => {
+  const fragmentIndex = sourceRef.indexOf("#");
+  const queryIndex = sourceRef.indexOf("?");
+  const suffixIndexes = [fragmentIndex, queryIndex].filter(
+    (index) => index >= 0
+  );
+  if (suffixIndexes.length === 0) return sourceRef;
+  return sourceRef.slice(0, Math.min(...suffixIndexes));
+};
+
+export const resolveCandidateRelPath = (
+  sourceRef: string,
+  ctx: AttachmentPathContext,
+  kind: "markdown" | "obsidian"
+):
+  | { ok: true; relPath: string }
+  | { ok: false; diagnostic: AttachmentDiagnostic } => {
+  // Markdown destinations follow URL semantics: raw query/fragment suffixes
+  // are not part of the local filename. Split before percent-decoding so an
+  // encoded literal `%23` or `%3F` can still address a real filename.
+  const pathSourceRef =
+    kind === "markdown" ? stripMarkdownUrlSuffix(sourceRef) : sourceRef;
+  const decoded = percentDecodeOnce(pathSourceRef);
+  const securityDecoded = safePercentDecode(pathSourceRef);
+  if (decoded === null || securityDecoded === null || decoded.trim() === "") {
+    return {
+      ok: false,
+      diagnostic: diagnostic(
+        "ASSET_CORRUPT",
+        "Malformed image reference encoding",
+        ctx.noteSlug,
+        sourceRef
+      ),
+    };
+  }
+  if (
+    decoded.includes("\0") ||
+    decoded.includes("\\") ||
+    securityDecoded.includes("\\")
+  ) {
+    return {
+      ok: false,
+      diagnostic: diagnostic(
+        "ASSET_TRAVERSAL",
+        "Image reference escapes the approved collection root",
+        ctx.noteSlug,
+        sourceRef
+      ),
+    };
+  }
+  if (
+    isAbsolute(decoded) ||
+    pathPosix.isAbsolute(decoded) ||
+    isAbsolute(securityDecoded) ||
+    pathPosix.isAbsolute(securityDecoded)
+  ) {
+    return {
+      ok: false,
+      diagnostic: diagnostic(
+        "ASSET_TRAVERSAL",
+        "Absolute image paths are not allowed",
+        ctx.noteSlug,
+        sourceRef
+      ),
+    };
+  }
+
+  const hasSlash = decoded.includes("/");
+  if (!hasSlash && kind === "obsidian") {
+    const matches = ctx.basenameIndex.get(pathPosix.basename(decoded)) ?? [];
+    if (matches.length === 0) {
+      return {
+        ok: false,
+        diagnostic: diagnostic(
+          "ASSET_MISSING",
+          `No file named "${pathPosix.basename(decoded)}" under collection root`,
+          ctx.noteSlug,
+          sourceRef
+        ),
+      };
+    }
+    if (matches.length > 1) {
+      return {
+        ok: false,
+        diagnostic: diagnostic(
+          "ASSET_AMBIGUOUS",
+          `Ambiguous basename "${pathPosix.basename(decoded)}" matches ${matches.length} files`,
+          ctx.noteSlug,
+          sourceRef
+        ),
+      };
+    }
+    return { ok: true, relPath: matches[0]! };
+  }
+
+  const baseDir =
+    kind === "obsidian" && hasSlash ? "" : pathPosix.dirname(ctx.sourceRelPath);
+  const joined = pathPosix.normalize(
+    pathPosix.join(baseDir === "." ? "" : baseDir, decoded)
+  );
+  const securityJoined = pathPosix.normalize(
+    pathPosix.join(baseDir === "." ? "" : baseDir, securityDecoded)
+  );
+  if (
+    joined.startsWith("..") ||
+    joined.split("/").includes("..") ||
+    pathPosix.isAbsolute(joined) ||
+    securityJoined.startsWith("..") ||
+    securityJoined.split("/").includes("..") ||
+    pathPosix.isAbsolute(securityJoined)
+  ) {
+    return {
+      ok: false,
+      diagnostic: diagnostic(
+        "ASSET_TRAVERSAL",
+        "Image reference escapes the approved collection root",
+        ctx.noteSlug,
+        sourceRef
+      ),
+    };
+  }
+  if (
+    isPrivateAttachmentRelPath(joined) ||
+    matchesCollectionExclusion(joined, ctx.collectionExcludes ?? [])
+  ) {
+    return {
+      ok: false,
+      diagnostic: diagnostic(
+        "ASSET_MISSING",
+        "Attachment not found",
+        ctx.noteSlug,
+        sourceRef
+      ),
+    };
+  }
+  return { ok: true, relPath: joined.replace(/^\.\//u, "") };
+};
+
+export async function assertContainedFile(
+  collectionRoot: string,
+  relPath: string,
+  noteSlug: string,
+  sourceRef: string,
+  collectionExcludes: readonly string[] = []
+): Promise<{ absPath: string } | AttachmentDiagnostic> {
+  const rootReal = await realpath(normalize(collectionRoot));
+  const absLexical = normalize(join(rootReal, ...relPath.split("/")));
+  if (!isCanonicalPathContained(rootReal, absLexical)) {
+    throw new Error(
+      `ASSET_TRAVERSAL: image path escapes collection root (${sourceRef})`
+    );
+  }
+  let info: Awaited<ReturnType<typeof lstat>>;
+  try {
+    info = await lstat(absLexical);
+  } catch {
+    return diagnostic(
+      "ASSET_MISSING",
+      `Attachment not found: ${relPath}`,
+      noteSlug,
+      sourceRef
+    );
+  }
+  if (info.isSymbolicLink()) {
+    throw new Error(
+      `ASSET_TRAVERSAL: refusing symlink attachment (${sourceRef})`
+    );
+  }
+  if (!info.isFile()) {
+    return diagnostic(
+      "ASSET_MISSING",
+      `Attachment is not a regular file: ${relPath}`,
+      noteSlug,
+      sourceRef
+    );
+  }
+  let absReal: string;
+  try {
+    absReal = await realpath(absLexical);
+  } catch {
+    throw new Error(
+      `ASSET_TRAVERSAL: unable to realpath attachment (${sourceRef})`
+    );
+  }
+  if (!isCanonicalPathContained(rootReal, absReal)) {
+    throw new Error(
+      `ASSET_TRAVERSAL: symlink escape outside collection root (${sourceRef})`
+    );
+  }
+  const canonicalRelPath = relative(rootReal, absReal).split(sep).join("/");
+  if (
+    isPrivateAttachmentRelPath(canonicalRelPath) ||
+    matchesCollectionExclusion(canonicalRelPath, collectionExcludes)
+  ) {
+    return diagnostic(
+      "ASSET_MISSING",
+      "Attachment not found",
+      noteSlug,
+      sourceRef
+    );
+  }
+  return { absPath: absReal };
+}