@gmickel/gno 1.32.0 → 1.34.0

package/src/publish/artifact-asset-codec.ts

@@ -0,0 +1,75 @@
+/**
+ * Synchronous SHA-256 + base64 helpers for publish assets.
+ * Bun.CryptoHasher for digests; browser-safe atob for base64 decode parity with gno.sh.
+ *
+ * @module src/publish/artifact-asset-codec
+ */
+
+/** Synchronous SHA-256 hex digest over raw bytes (Bun-native). */
+export const sha256BytesHex = (bytes: Uint8Array): string => {
+  const hasher = new Bun.CryptoHasher("sha256");
+  hasher.update(bytes);
+  return hasher.digest("hex");
+};
+
+const BASE64_PATTERN =
+  /^(?:[a-zA-Z0-9+/]{4})*(?:[a-zA-Z0-9+/]{2}==|[a-zA-Z0-9+/]{3}=)?$/u;
+
+/**
+ * Encode raw bytes to standard base64 without Node Buffer.
+ * Prefers Bun/Web Uint8Array.toBase64(); falls back to btoa for parity with decode.
+ */
+export const encodeBytesToBase64 = (bytes: Uint8Array): string => {
+  if (typeof bytes.toBase64 === "function") {
+    return bytes.toBase64();
+  }
+  const CHUNK = 0x8000;
+  let binary = "";
+  for (let offset = 0; offset < bytes.length; offset += CHUNK) {
+    const slice = bytes.subarray(offset, offset + CHUNK);
+    binary += String.fromCharCode(...slice);
+  }
+  return btoa(binary);
+};
+
+/** Decode standard base64 without Buffer (uses atob). */
+export const decodeBase64ToBytes = (
+  data: string
+): { ok: true; bytes: Uint8Array } | { ok: false } => {
+  if (!BASE64_PATTERN.test(data) || data.length === 0) return { ok: false };
+  try {
+    const binary = atob(data);
+    if (binary.length === 0 && data.replace(/=+$/u, "").length > 0) {
+      return { ok: false };
+    }
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i += 1) {
+      bytes[i] = binary.charCodeAt(i);
+    }
+    return { ok: true, bytes };
+  } catch {
+    return { ok: false };
+  }
+};
+
+const UTF8 = new TextEncoder();
+
+export const measureSerializedUploadBytes = (serializedBody: string): number =>
+  UTF8.encode(serializedBody).byteLength;
+
+/**
+ * Canonical on-disk/upload serialization for publish artifacts.
+ *
+ * Byte-budget enforcement and every artifact writer must use this exact
+ * representation so `finalUploadBytes` describes the bytes handed to gno.sh.
+ */
+export const serializePublishArtifact = (artifact: unknown): string => {
+  const serialized = JSON.stringify(artifact, null, 2);
+  if (serialized === undefined) {
+    throw new TypeError("Publish artifact is not JSON-serializable");
+  }
+  return serialized;
+};
+
+export const measureArtifactUploadBytes = (artifact: unknown): number =>
+  measureSerializedUploadBytes(serializePublishArtifact(artifact));

package/src/publish/artifact-asset-contract.ts

@@ -0,0 +1,152 @@
+/**
+ * Shared publish-asset contract vocabulary (producer/consumer).
+ *
+ * @module src/publish/artifact-asset-contract
+ */
+
+export const MAX_PUBLISH_UPLOAD_BYTES = 100 * 1024 * 1024;
+
+/** Schema bounds for asset reference sourceRef (publish-artifact.schema.json). */
+export const MIN_SOURCE_REF_LENGTH = 1;
+export const MAX_SOURCE_REF_LENGTH = 1024;
+
+export const BUNDLED_RASTER_ASSETS_CAPABILITY =
+  "bundled-raster-assets@1" as const;
+
+export const KNOWN_PUBLISH_REQUIRED_CAPABILITIES = [
+  BUNDLED_RASTER_ASSETS_CAPABILITY,
+] as const;
+
+/** Schema bounds for requiredCapabilities entries (publish-artifact.schema.json). */
+export const MIN_REQUIRED_CAPABILITY_LENGTH = 1;
+export const MAX_REQUIRED_CAPABILITY_LENGTH = 128;
+
+export type KnownPublishRequiredCapability =
+  (typeof KNOWN_PUBLISH_REQUIRED_CAPABILITIES)[number];
+
+export const SUPPORTED_RASTER_MEDIA_TYPES = [
+  "image/png",
+  "image/jpeg",
+  "image/gif",
+  "image/webp",
+  "image/avif",
+] as const;
+
+export type SupportedRasterMediaType =
+  (typeof SUPPORTED_RASTER_MEDIA_TYPES)[number];
+
+export const MAX_RASTER_DIMENSION_PX = 16_384;
+export const MIN_RASTER_DIMENSION_PX = 1;
+
+/** Strict sentinel: scheme + lowercase SHA-256 hex asset id. */
+export const GNO_ASSET_SENTINEL_PATTERN = /^gno-asset:([a-f0-9]{64})$/u;
+export const GNO_ASSET_SENTINEL_PREFIX = "gno-asset:";
+
+export const PUBLISH_ASSET_NOTE_SLUG_PATTERN =
+  /^[a-z0-9](?:[a-z0-9-]{0,78}[a-z0-9])?$/u;
+
+export const PUBLISH_ASSET_VISIBILITY = {
+  public: {
+    class: "public",
+    delivery: "immutable-public-url",
+    storage: "private-until-public-commit",
+    notes:
+      "Validated assets may use immutable public URLs only after the share is classified public.",
+  },
+  "secret-link": {
+    class: "secret",
+    delivery: "capability-authorized",
+    storage: "private",
+    forbids: ["public-object-url", "presigned-url-as-sole-authorization"],
+    notes:
+      "Secret is an authorization boundary; private storage delivery requires the secret-share capability.",
+  },
+  encrypted: {
+    class: "encrypted",
+    delivery: "client-blob-url",
+    storage: "none-plaintext",
+    assetPlacement: "encrypted-client-payload",
+    notes:
+      "Plaintext image bytes remain inside the encrypted client payload; Blob URLs are revoked on replacement/unmount.",
+  },
+} as const;
+
+export const PUBLISH_ASSET_LIFECYCLE_TERMINALS = [
+  "committed",
+  "rolled_back",
+  "deleted",
+  "orphan_cleaned",
+  "idempotent_noop",
+] as const;
+
+export type PublishAssetLifecycleTerminal =
+  (typeof PUBLISH_ASSET_LIFECYCLE_TERMINALS)[number];
+
+export const PUBLISH_ASSET_DIAGNOSTIC_CODES = [
+  "ASSET_MISSING",
+  "ASSET_CONFLICT",
+  "ASSET_SENTINEL_RAW",
+  "ASSET_SENTINEL_UNRESOLVED",
+  "ASSET_SENTINEL_INVALID",
+  "ASSET_TRAVERSAL",
+  "ASSET_MIME_SPOOF",
+  "ASSET_OVERSIZE",
+  "ASSET_CORRUPT",
+  "ASSET_UNSUPPORTED_FORMAT",
+  "ASSET_DIMENSION_INVALID",
+  "CAPABILITY_UNSUPPORTED",
+  "ENVELOPE_OVERSIZE",
+] as const;
+
+export type PublishAssetDiagnosticCode =
+  (typeof PUBLISH_ASSET_DIAGNOSTIC_CODES)[number];
+
+export interface PublishArtifactAssetReference {
+  noteSlug: string;
+  sourceRef: string;
+}
+
+export interface PublishArtifactAsset {
+  byteLength: number;
+  data: string;
+  encoding: "base64";
+  height: number;
+  id: string;
+  mediaType: string;
+  references: Array<PublishArtifactAssetReference>;
+  sha256: string;
+  width: number;
+}
+
+export interface PublishAssetDiagnostic {
+  code: PublishAssetDiagnosticCode;
+  message: string;
+}
+
+export type PublishAssetClassification =
+  | "asset-free"
+  | "bundled-raster-v1"
+  | "encrypted-client-payload";
+
+export type PublishAssetContractResult =
+  | { ok: true; classification: PublishAssetClassification }
+  | { ok: false; diagnostic: PublishAssetDiagnostic };
+
+export interface ValidatePublishAssetContractOptions {
+  /** Exact UTF-8 byte length of the final upload body when already serialized. */
+  serializedUploadBytes?: number;
+}
+
+export const ASSET_DESCRIPTOR_KEYS = [
+  "byteLength",
+  "data",
+  "encoding",
+  "height",
+  "id",
+  "mediaType",
+  "references",
+  "sha256",
+  "width",
+] as const;
+
+export const ASSET_REFERENCE_KEYS = ["noteSlug", "sourceRef"] as const;

package/src/publish/artifact-asset-parse.ts

@@ -0,0 +1,401 @@
+/**
+ * Closed-object parsing and sourceRef threat checks for publish assets.
+ *
+ * @module src/publish/artifact-asset-parse
+ */
+
+import { decodeBase64ToBytes, sha256BytesHex } from "./artifact-asset-codec";
+import {
+  ASSET_DESCRIPTOR_KEYS,
+  ASSET_REFERENCE_KEYS,
+  KNOWN_PUBLISH_REQUIRED_CAPABILITIES,
+  MAX_PUBLISH_UPLOAD_BYTES,
+  MAX_RASTER_DIMENSION_PX,
+  MAX_REQUIRED_CAPABILITY_LENGTH,
+  MAX_SOURCE_REF_LENGTH,
+  MIN_RASTER_DIMENSION_PX,
+  MIN_REQUIRED_CAPABILITY_LENGTH,
+  MIN_SOURCE_REF_LENGTH,
+  PUBLISH_ASSET_NOTE_SLUG_PATTERN,
+  SUPPORTED_RASTER_MEDIA_TYPES,
+  type PublishArtifactAsset,
+  type PublishArtifactAssetReference,
+  type PublishAssetDiagnostic,
+  type PublishAssetDiagnosticCode,
+  type SupportedRasterMediaType,
+} from "./artifact-asset-contract";
+import { parseGnoAssetSentinel } from "./artifact-asset-sniff";
+import { discoverImageOccurrences } from "./attachment-discover";
+import { validateRasterBytesStructural } from "./attachment-raster";
+
+const SHA256_HEX_PATTERN = /^[a-f0-9]{64}$/u;
+const TRAVERSAL_PATTERN = /(?:^|[\\/])\.\.(?:[\\/]|$)|^\/|^[a-zA-Z]:[\\/]/u;
+const ABSOLUTE_PATTERN = /^(?:\/|\\|[a-zA-Z]:[\\/])/u;
+
+export type ContractFailure = {
+  ok: false;
+  diagnostic: PublishAssetDiagnostic;
+};
+
+export const fail = (
+  code: PublishAssetDiagnosticCode,
+  message: string
+): ContractFailure => ({
+  ok: false,
+  diagnostic: { code, message },
+});
+
+const isSupportedMediaType = (
+  value: string
+): value is SupportedRasterMediaType =>
+  (SUPPORTED_RASTER_MEDIA_TYPES as ReadonlyArray<string>).includes(value);
+
+const sortedKeysEqual = (
+  keys: Array<string>,
+  expected: ReadonlyArray<string>
+): boolean =>
+  JSON.stringify([...keys].sort()) === JSON.stringify([...expected].sort());
+
+export const collectMarkdownSentinels = (
+  markdown: string
+): ContractFailure | { ok: true; ids: Set<string> } => {
+  const ids = new Set<string>();
+  for (const occurrence of discoverImageOccurrences(markdown, {
+    excludeFrontmatter: false,
+  })) {
+    const sourceRef = occurrence.sourceRef;
+    if (!sourceRef.startsWith("gno-asset:")) continue;
+    const parsed = parseGnoAssetSentinel(sourceRef);
+    if (!parsed.ok) {
+      return fail(
+        "ASSET_SENTINEL_INVALID",
+        `Invalid gno-asset sentinel grammar: "${sourceRef}"`
+      );
+    }
+    ids.add(parsed.assetId);
+  }
+  return { ok: true, ids };
+};
+
+const expandSourceRefForms = (sourceRef: string): Array<string> => {
+  const forms = [sourceRef];
+  let current = sourceRef;
+  for (let round = 0; round < 4; round += 1) {
+    if (!/%[0-9a-fA-F]{2}/u.test(current)) break;
+    try {
+      const decoded = decodeURIComponent(current);
+      if (decoded === current) break;
+      forms.push(decoded);
+      current = decoded;
+    } catch {
+      break;
+    }
+  }
+  return forms;
+};
+
+const validateSourceRef = (
+  sourceRef: string,
+  field: string
+): ContractFailure | null => {
+  if (typeof sourceRef !== "string") {
+    return fail("ASSET_CORRUPT", `${field} must be a string`);
+  }
+  // Enforce schema 1..1024 bound before percent-decode / traversal normalization.
+  // JSON Schema maxLength counts Unicode code points, not UTF-16 code units.
+  const sourceRefLength = Array.from(sourceRef).length;
+  if (
+    sourceRefLength < MIN_SOURCE_REF_LENGTH ||
+    sourceRefLength > MAX_SOURCE_REF_LENGTH
+  ) {
+    return fail(
+      "ASSET_CORRUPT",
+      `${field} must be ${MIN_SOURCE_REF_LENGTH}..${MAX_SOURCE_REF_LENGTH} characters`
+    );
+  }
+  if (sourceRef.trim().length === 0) {
+    return fail("ASSET_TRAVERSAL", `${field} must not be blank`);
+  }
+  for (const form of expandSourceRefForms(sourceRef)) {
+    if (
+      form.includes("\0") ||
+      TRAVERSAL_PATTERN.test(form) ||
+      ABSOLUTE_PATTERN.test(form)
+    ) {
+      return fail(
+        "ASSET_TRAVERSAL",
+        `${field} escapes the approved collection root`
+      );
+    }
+  }
+  return null;
+};
+
+const readClosedReference = (
+  value: unknown,
+  field: string
+): ContractFailure | { ok: true; reference: PublishArtifactAssetReference } => {
+  if (!(value && typeof value === "object" && !Array.isArray(value))) {
+    return fail("ASSET_CORRUPT", `${field} must be a closed object`);
+  }
+  const record = value as Record<string, unknown>;
+  if (!sortedKeysEqual(Object.keys(record), ASSET_REFERENCE_KEYS)) {
+    return fail("ASSET_CORRUPT", `${field} contains unknown or missing fields`);
+  }
+  if (typeof record.noteSlug !== "string" || record.noteSlug.trim() === "") {
+    return fail(
+      "ASSET_CORRUPT",
+      `${field}.noteSlug must be a non-empty string`
+    );
+  }
+  if (!PUBLISH_ASSET_NOTE_SLUG_PATTERN.test(record.noteSlug)) {
+    return fail(
+      "ASSET_CORRUPT",
+      `${field}.noteSlug must match publish note slug syntax`
+    );
+  }
+  if (typeof record.sourceRef !== "string") {
+    return fail("ASSET_CORRUPT", `${field}.sourceRef must be a string`);
+  }
+  const traversal = validateSourceRef(record.sourceRef, `${field}.sourceRef`);
+  if (traversal) return traversal;
+  return {
+    ok: true,
+    reference: {
+      noteSlug: record.noteSlug,
+      sourceRef: record.sourceRef,
+    },
+  };
+};
+
+const readClosedAsset = (
+  value: unknown,
+  index: number
+): ContractFailure | { ok: true; asset: PublishArtifactAsset } => {
+  const field = `assets[${index}]`;
+  if (!(value && typeof value === "object" && !Array.isArray(value))) {
+    return fail("ASSET_CORRUPT", `${field} must be a closed object`);
+  }
+  const record = value as Record<string, unknown>;
+  if (!sortedKeysEqual(Object.keys(record), ASSET_DESCRIPTOR_KEYS)) {
+    return fail("ASSET_CORRUPT", `${field} contains unknown or missing fields`);
+  }
+
+  if (typeof record.id !== "string" || typeof record.sha256 !== "string") {
+    return fail(
+      "ASSET_CORRUPT",
+      `${field} id/sha256 must be lowercase SHA-256 hex`
+    );
+  }
+  if (
+    !SHA256_HEX_PATTERN.test(record.id) ||
+    !SHA256_HEX_PATTERN.test(record.sha256)
+  ) {
+    return fail(
+      "ASSET_CORRUPT",
+      `${field} id/sha256 must be lowercase SHA-256 hex`
+    );
+  }
+  if (record.id !== record.sha256) {
+    return fail(
+      "ASSET_CONFLICT",
+      `${field} id must equal sha256 of payload bytes`
+    );
+  }
+  if (record.encoding !== "base64") {
+    return fail("ASSET_CORRUPT", `${field}.encoding must be "base64"`);
+  }
+  if (
+    typeof record.byteLength !== "number" ||
+    !Number.isSafeInteger(record.byteLength) ||
+    record.byteLength < 1
+  ) {
+    return fail(
+      "ASSET_CORRUPT",
+      `${field}.byteLength must be a positive integer`
+    );
+  }
+  if (record.byteLength > MAX_PUBLISH_UPLOAD_BYTES) {
+    return fail(
+      "ASSET_OVERSIZE",
+      `${field}.byteLength exceeds the ${MAX_PUBLISH_UPLOAD_BYTES} byte upload ceiling`
+    );
+  }
+  if (
+    typeof record.width !== "number" ||
+    typeof record.height !== "number" ||
+    !Number.isSafeInteger(record.width) ||
+    !Number.isSafeInteger(record.height) ||
+    record.width < MIN_RASTER_DIMENSION_PX ||
+    record.height < MIN_RASTER_DIMENSION_PX ||
+    record.width > MAX_RASTER_DIMENSION_PX ||
+    record.height > MAX_RASTER_DIMENSION_PX
+  ) {
+    return fail(
+      "ASSET_DIMENSION_INVALID",
+      `${field} dimensions must be integers in ${MIN_RASTER_DIMENSION_PX}..${MAX_RASTER_DIMENSION_PX}`
+    );
+  }
+  if (!Array.isArray(record.references) || record.references.length === 0) {
+    return fail(
+      "ASSET_CORRUPT",
+      `${field}.references must be a non-empty array`
+    );
+  }
+
+  const references: Array<PublishArtifactAssetReference> = [];
+  for (const [refIndex, entry] of record.references.entries()) {
+    const parsed = readClosedReference(
+      entry,
+      `${field}.references[${refIndex}]`
+    );
+    if (!parsed.ok) return parsed;
+    references.push(parsed.reference);
+  }
+
+  if (typeof record.mediaType !== "string") {
+    return fail(
+      "ASSET_UNSUPPORTED_FORMAT",
+      `${field}.mediaType "${String(record.mediaType)}" is unsupported (SVG excluded)`
+    );
+  }
+  if (record.mediaType === "image/svg+xml") {
+    return fail(
+      "ASSET_UNSUPPORTED_FORMAT",
+      `${field}.mediaType "image/svg+xml" is unsupported (SVG excluded)`
+    );
+  }
+  if (!isSupportedMediaType(record.mediaType)) {
+    return fail(
+      "ASSET_UNSUPPORTED_FORMAT",
+      `${field}.mediaType "${record.mediaType}" is not a supported raster type`
+    );
+  }
+  if (typeof record.data !== "string") {
+    return fail("ASSET_CORRUPT", `${field}.data must be valid base64`);
+  }
+
+  const decoded = decodeBase64ToBytes(record.data);
+  if (!decoded.ok) {
+    return fail("ASSET_CORRUPT", `${field}.data must be valid base64`);
+  }
+  if (decoded.bytes.byteLength !== record.byteLength) {
+    return fail(
+      "ASSET_CORRUPT",
+      `${field}.byteLength does not match decoded payload length`
+    );
+  }
+  const digest = sha256BytesHex(decoded.bytes);
+  if (digest !== record.sha256) {
+    return fail(
+      "ASSET_CORRUPT",
+      `${field}.sha256 does not match payload bytes`
+    );
+  }
+  // Closed-object parse stays synchronous: structural validation only.
+  // Producer/file-ingress paths must await validateRasterDecodable separately.
+  const validatedRaster = validateRasterBytesStructural(decoded.bytes);
+  if (!validatedRaster.ok) {
+    return fail(validatedRaster.code, `${field} ${validatedRaster.message}`);
+  }
+  if (validatedRaster.mediaType !== record.mediaType) {
+    return fail(
+      "ASSET_MIME_SPOOF",
+      `${field} declared ${record.mediaType} but bytes sniff as ${validatedRaster.mediaType}`
+    );
+  }
+  if (
+    validatedRaster.width !== record.width ||
+    validatedRaster.height !== record.height
+  ) {
+    return fail(
+      "ASSET_DIMENSION_INVALID",
+      `${field} declared ${record.width}x${record.height} but bytes are ${validatedRaster.width}x${validatedRaster.height}`
+    );
+  }
+
+  return {
+    ok: true,
+    asset: {
+      byteLength: record.byteLength,
+      data: record.data,
+      encoding: "base64",
+      height: record.height,
+      id: record.id,
+      mediaType: record.mediaType,
+      references,
+      sha256: record.sha256,
+      width: record.width,
+    },
+  };
+};
+
+export const readRequiredCapabilities = (
+  value: unknown
+): ContractFailure | { ok: true; capabilities: Array<string> } => {
+  if (value === undefined) return { ok: true, capabilities: [] };
+  if (
+    !Array.isArray(value) ||
+    value.some((entry) => typeof entry !== "string")
+  ) {
+    return fail(
+      "CAPABILITY_UNSUPPORTED",
+      "requiredCapabilities must be an array of strings when present"
+    );
+  }
+  const capabilities = value as Array<string>;
+  const seen = new Set<string>();
+  for (const capability of capabilities) {
+    if (
+      capability.length < MIN_REQUIRED_CAPABILITY_LENGTH ||
+      capability.length > MAX_REQUIRED_CAPABILITY_LENGTH
+    ) {
+      return fail(
+        "CAPABILITY_UNSUPPORTED",
+        `requiredCapabilities entries must be non-empty strings of at most ${MAX_REQUIRED_CAPABILITY_LENGTH} characters`
+      );
+    }
+    if (seen.has(capability)) {
+      return fail(
+        "CAPABILITY_UNSUPPORTED",
+        `requiredCapabilities duplicates capability "${capability}"`
+      );
+    }
+    seen.add(capability);
+    if (
+      !(KNOWN_PUBLISH_REQUIRED_CAPABILITIES as ReadonlyArray<string>).includes(
+        capability
+      )
+    ) {
+      return fail(
+        "CAPABILITY_UNSUPPORTED",
+        `Unsupported required capability "${capability}"`
+      );
+    }
+  }
+  return { ok: true, capabilities };
+};
+
+export const readAssets = (
+  value: unknown
+): ContractFailure | { ok: true; assets: Array<PublishArtifactAsset> } => {
+  if (value === undefined) return { ok: true, assets: [] };
+  if (!Array.isArray(value)) {
+    return fail("ASSET_CORRUPT", "assets must be an array when present");
+  }
+  const assets: Array<PublishArtifactAsset> = [];
+  const seenIds = new Set<string>();
+  for (const [index, entry] of value.entries()) {
+    const parsed = readClosedAsset(entry, index);
+    if (!parsed.ok) return parsed;
+    if (seenIds.has(parsed.asset.id)) {
+      return fail(
+        "ASSET_CONFLICT",
+        `assets[${index}] duplicates asset id ${parsed.asset.id}; dedup requires one descriptor per content id`
+      );
+    }
+    seenIds.add(parsed.asset.id);
+    assets.push(parsed.asset);
+  }
+  return { ok: true, assets };
+};