@gmickel/gno 1.32.0 → 1.33.0

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

@@ -0,0 +1,209 @@
+/**
+ * Fail-closed runtime validation for optional publish raster assets.
+ *
+ * @module src/publish/artifact-asset-validate
+ */
+
+import { measureArtifactUploadBytes } from "./artifact-asset-codec";
+import {
+  BUNDLED_RASTER_ASSETS_CAPABILITY,
+  MAX_PUBLISH_UPLOAD_BYTES,
+  type PublishArtifactAsset,
+  type PublishAssetContractResult,
+  type ValidatePublishAssetContractOptions,
+} from "./artifact-asset-contract";
+import {
+  collectMarkdownSentinels,
+  fail,
+  readAssets,
+  readRequiredCapabilities,
+  type ContractFailure,
+} from "./artifact-asset-parse";
+
+type NoteIndex = {
+  markdownBySlug: Map<string, string[]>;
+  slugs: Set<string>;
+};
+
+const collectNoteIndex = (artifact: Record<string, unknown>): NoteIndex => {
+  const markdownBySlug = new Map<string, string[]>();
+  const slugs = new Set<string>();
+  const spaces = Array.isArray(artifact.spaces) ? artifact.spaces : [];
+  for (const space of spaces) {
+    if (!(space && typeof space === "object" && !Array.isArray(space)))
+      continue;
+    const record = space as Record<string, unknown>;
+    if (!Array.isArray(record.notes)) continue;
+    for (const note of record.notes) {
+      if (!(note && typeof note === "object" && !Array.isArray(note))) continue;
+      const noteRecord = note as Record<string, unknown>;
+      if (typeof noteRecord.slug !== "string") continue;
+      slugs.add(noteRecord.slug);
+      if (typeof noteRecord.markdown === "string") {
+        const markdownEntries = markdownBySlug.get(noteRecord.slug) ?? [];
+        markdownEntries.push(noteRecord.markdown);
+        markdownBySlug.set(noteRecord.slug, markdownEntries);
+      }
+    }
+  }
+  return { markdownBySlug, slugs };
+};
+
+const collectNoteMarkdown = (notes: NoteIndex): Array<string> =>
+  [...notes.markdownBySlug.values()].flat();
+
+const validateReferenceOwnership = (
+  assets: Array<PublishArtifactAsset>,
+  notes: NoteIndex,
+  sentinelOwners: Map<string, Set<string>>
+): ContractFailure | null => {
+  for (const [index, asset] of assets.entries()) {
+    const field = `assets[${index}]`;
+    const owners = sentinelOwners.get(asset.id) ?? new Set<string>();
+    if (owners.size === 0) {
+      return fail(
+        "ASSET_MISSING",
+        `${field} has no matching gno-asset sentinel in any artifact note`
+      );
+    }
+    const claimed = new Set<string>();
+    for (const [refIndex, reference] of asset.references.entries()) {
+      if (!notes.slugs.has(reference.noteSlug)) {
+        return fail(
+          "ASSET_MISSING",
+          `${field}.references[${refIndex}].noteSlug "${reference.noteSlug}" does not own an artifact note`
+        );
+      }
+      claimed.add(reference.noteSlug);
+      if (!owners.has(reference.noteSlug)) {
+        return fail(
+          "ASSET_SENTINEL_UNRESOLVED",
+          `${field}.references[${refIndex}] claims note "${reference.noteSlug}" without a matching gno-asset sentinel`
+        );
+      }
+    }
+    for (const owner of owners) {
+      if (!claimed.has(owner)) {
+        return fail(
+          "ASSET_SENTINEL_UNRESOLVED",
+          `${field} is referenced by note "${owner}" but references[] omits that ownership`
+        );
+      }
+    }
+  }
+  return null;
+};
+
+/**
+ * Executable producer/consumer contract for optional raster assets.
+ * Legacy asset-free v1/v2 artifacts remain accepted.
+ */
+export const validatePublishAssetContract = (
+  artifact: unknown,
+  options: ValidatePublishAssetContractOptions = {}
+): PublishAssetContractResult => {
+  if (!(artifact && typeof artifact === "object" && !Array.isArray(artifact))) {
+    return fail("ASSET_CORRUPT", "Artifact must be an object");
+  }
+  const record = artifact as Record<string, unknown>;
+  const serializedBytes =
+    options.serializedUploadBytes ?? measureArtifactUploadBytes(artifact);
+  if (serializedBytes > MAX_PUBLISH_UPLOAD_BYTES) {
+    return fail(
+      "ENVELOPE_OVERSIZE",
+      `Final serialized upload is ${serializedBytes} bytes; max is ${MAX_PUBLISH_UPLOAD_BYTES}`
+    );
+  }
+
+  const capabilitiesResult = readRequiredCapabilities(
+    record.requiredCapabilities
+  );
+  if (!capabilitiesResult.ok) return capabilitiesResult;
+  const assetsResult = readAssets(record.assets);
+  if (!assetsResult.ok) return assetsResult;
+
+  const { capabilities } = capabilitiesResult;
+  const { assets } = assetsResult;
+  const requiresBundled = capabilities.includes(
+    BUNDLED_RASTER_ASSETS_CAPABILITY
+  );
+  const notes = collectNoteIndex(record);
+  const version = record.version;
+
+  if (version === 2) {
+    if (assets.length > 0) {
+      return fail(
+        "ASSET_CONFLICT",
+        "Encrypted v2 artifacts must not carry plaintext assets on the outer envelope"
+      );
+    }
+    for (const markdown of collectNoteMarkdown(notes)) {
+      const sentinels = collectMarkdownSentinels(markdown);
+      if (!sentinels.ok) return sentinels;
+      if (sentinels.ids.size > 0) {
+        return fail(
+          "ASSET_SENTINEL_RAW",
+          "Encrypted v2 outer envelopes must not contain plaintext gno-asset sentinels"
+        );
+      }
+    }
+    if (requiresBundled) {
+      return { ok: true, classification: "encrypted-client-payload" };
+    }
+    return { ok: true, classification: "asset-free" };
+  }
+
+  const referencedIds = new Set<string>();
+  const sentinelOwners = new Map<string, Set<string>>();
+  for (const [slug, markdownEntries] of notes.markdownBySlug.entries()) {
+    for (const markdown of markdownEntries) {
+      const sentinels = collectMarkdownSentinels(markdown);
+      if (!sentinels.ok) return sentinels;
+      for (const id of sentinels.ids) {
+        referencedIds.add(id);
+        const owners = sentinelOwners.get(id) ?? new Set<string>();
+        owners.add(slug);
+        sentinelOwners.set(id, owners);
+      }
+    }
+  }
+
+  if (referencedIds.size > 0 && !requiresBundled && assets.length === 0) {
+    return fail(
+      "ASSET_SENTINEL_RAW",
+      "Unresolved gno-asset sentinels must never reach render; declare bundled-raster-assets@1 and include assets"
+    );
+  }
+
+  if (assets.length > 0 && !requiresBundled) {
+    return fail(
+      "CAPABILITY_UNSUPPORTED",
+      "assets require requiredCapabilities to include bundled-raster-assets@1"
+    );
+  }
+
+  if (assets.length === 0 && referencedIds.size === 0) {
+    return { ok: true, classification: "asset-free" };
+  }
+
+  for (const id of referencedIds) {
+    if (!assets.some((asset) => asset.id === id)) {
+      return fail(
+        "ASSET_MISSING",
+        `Markdown references gno-asset:${id} but no matching asset descriptor is present`
+      );
+    }
+  }
+
+  if (referencedIds.size > 0 && assets.length === 0) {
+    return fail(
+      "ASSET_MISSING",
+      "Markdown contains gno-asset sentinels but assets[] is empty"
+    );
+  }
+
+  const ownership = validateReferenceOwnership(assets, notes, sentinelOwners);
+  if (ownership) return ownership;
+
+  return { ok: true, classification: "bundled-raster-v1" };
+};

package/src/publish/artifact-assets.ts

@@ -0,0 +1,58 @@
+/**
+ * Cross-repo publish artifact raster-asset contract (producer side).
+ *
+ * Freezes capability negotiation, sentinel grammar, byte accounting,
+ * signature sniffing, visibility/lifecycle vocabulary, and fail-closed
+ * diagnostics. Does not resolve filesystem attachments or deliver objects.
+ *
+ * Public import path remains `./artifact-assets` / `src/publish/artifact-assets`.
+ *
+ * @module src/publish/artifact-assets
+ */
+
+export type {
+  KnownPublishRequiredCapability,
+  PublishArtifactAsset,
+  PublishArtifactAssetReference,
+  PublishAssetClassification,
+  PublishAssetContractResult,
+  PublishAssetDiagnostic,
+  PublishAssetDiagnosticCode,
+  PublishAssetLifecycleTerminal,
+  SupportedRasterMediaType,
+  ValidatePublishAssetContractOptions,
+} from "./artifact-asset-contract";
+export {
+  ASSET_DESCRIPTOR_KEYS,
+  ASSET_REFERENCE_KEYS,
+  BUNDLED_RASTER_ASSETS_CAPABILITY,
+  GNO_ASSET_SENTINEL_PATTERN,
+  GNO_ASSET_SENTINEL_PREFIX,
+  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_DIAGNOSTIC_CODES,
+  PUBLISH_ASSET_LIFECYCLE_TERMINALS,
+  PUBLISH_ASSET_NOTE_SLUG_PATTERN,
+  PUBLISH_ASSET_VISIBILITY,
+  SUPPORTED_RASTER_MEDIA_TYPES,
+} from "./artifact-asset-contract";
+export {
+  decodeBase64ToBytes,
+  measureArtifactUploadBytes,
+  measureSerializedUploadBytes,
+  serializePublishArtifact,
+  sha256BytesHex,
+} from "./artifact-asset-codec";
+export {
+  formatGnoAssetSentinel,
+  matchGnoAssetTokens,
+  parseGnoAssetSentinel,
+  sniffRasterMediaType,
+} from "./artifact-asset-sniff";
+export { validatePublishAssetContract } from "./artifact-asset-validate";

package/src/publish/artifact-validation.ts

@@ -4,11 +4,27 @@
  * @module src/publish/artifact-validation
  */
 
+import { MAX_PUBLISH_UPLOAD_BYTES } from "./artifact-asset-contract";
+
 export const MAX_PUBLISH_SLUG_LENGTH = 80;
-export const MAX_ENCRYPTED_CIPHERTEXT_BASE64_LENGTH = 67_108_864;
+/**
+ * Ciphertext base64 character ceiling aligned to the 100 MiB final-envelope
+ * budget. Exact final serialized UTF-8 measurement remains the authoritative
+ * upload gate; this bound only prevents a single field from exceeding what the
+ * envelope itself could ever carry.
+ */
+export const MAX_ENCRYPTED_CIPHERTEXT_BASE64_LENGTH = MAX_PUBLISH_UPLOAD_BYTES;
 export const MAX_ENCRYPTED_KEY_MATERIAL_BASE64_LENGTH = 1024;
 export const MAX_ENCRYPTED_SECRET_TOKEN_LENGTH = 512;
 
+/** Length-only seam for ciphertext budget tests (avoids allocating huge strings). */
+export const encryptedCiphertextCharLengthAllowed = (
+  charLength: number
+): boolean =>
+  Number.isSafeInteger(charLength) &&
+  charLength >= 1 &&
+  charLength <= MAX_ENCRYPTED_CIPHERTEXT_BASE64_LENGTH;
+
 const PUBLISH_SLUG_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,78}[a-z0-9])?$/u;
 const BASE64_PATTERN =
   /^(?:[a-zA-Z0-9+/]{4})*(?:[a-zA-Z0-9+/]{2}==|[a-zA-Z0-9+/]{3}=)?$/u;
@@ -95,6 +111,20 @@ const requireBase64 = (
   return result;
 };
 
+const requireEncryptedCiphertext = (value: unknown): string => {
+  const field = "encryptedPayload.ciphertext";
+  const result = requireNonblankString(value, field);
+  if (!encryptedCiphertextCharLengthAllowed(result.length)) {
+    throw new Error(
+      `${field} must not exceed ${MAX_ENCRYPTED_CIPHERTEXT_BASE64_LENGTH} characters`
+    );
+  }
+  if (!BASE64_PATTERN.test(result)) {
+    throw new Error(`${field} must be valid base64`);
+  }
+  return result;
+};
+
 const requireSlug = (value: unknown, field: string): string => {
   const result = requireString(value, field);
   if (!PUBLISH_SLUG_PATTERN.test(result)) {
@@ -217,11 +247,7 @@ export const validateAndProjectEncryptedPublishInput = (
 
   return {
     encryptedPayload: {
-      ciphertext: requireBase64(
-        payload.ciphertext,
-        "encryptedPayload.ciphertext",
-        MAX_ENCRYPTED_CIPHERTEXT_BASE64_LENGTH
-      ),
+      ciphertext: requireEncryptedCiphertext(payload.ciphertext),
       iterations,
       iv: requireBase64(
         payload.iv,

package/src/publish/artifact.ts

@@ -6,6 +6,10 @@
 
 import type { EgressLineage } from "../core/egress-provenance";
 import type { DocumentRow } from "../store/types";
+import type {
+  KnownPublishRequiredCapability,
+  PublishArtifactAsset,
+} from "./artifact-assets";
 
 import { deriveDocid } from "../app/constants";
 import {
@@ -26,7 +30,37 @@ import {
 
 export { MAX_PUBLISH_SLUG_LENGTH } from "./artifact-validation";
 export { buildExportedMetadata } from "./metadata";
-
+export type {
+  PublishArtifactAsset,
+  PublishArtifactAssetReference,
+  SupportedRasterMediaType,
+} from "./artifact-assets";
+export {
+  BUNDLED_RASTER_ASSETS_CAPABILITY,
+  GNO_ASSET_SENTINEL_PATTERN,
+  MAX_PUBLISH_UPLOAD_BYTES,
+  PUBLISH_ASSET_DIAGNOSTIC_CODES,
+  PUBLISH_ASSET_LIFECYCLE_TERMINALS,
+  PUBLISH_ASSET_VISIBILITY,
+  SUPPORTED_RASTER_MEDIA_TYPES,
+  formatGnoAssetSentinel,
+  measureArtifactUploadBytes,
+  measureSerializedUploadBytes,
+  parseGnoAssetSentinel,
+  serializePublishArtifact,
+  sniffRasterMediaType,
+  validatePublishAssetContract,
+} from "./artifact-assets";
+export {
+  attachAssetsToV1Artifact,
+  buildDeterministicAssets,
+  emptyAssetEgressSummary,
+  summarizeAssetEgress,
+} from "./attachment-resolver";
+export type {
+  AttachmentDiagnostic,
+  PublishAssetEgressSummary,
+} from "./attachment-resolver";
 export type PublishVisibility =
   | "encrypted"
   | "invite-only"
@@ -122,8 +156,10 @@ export interface EncryptedPublishArtifactSpace {
 }
 
 export interface PublishArtifactV1 {
+  assets?: PublishArtifactAsset[];
   egressLineage: EgressLineage;
   exportedAt: string;
+  requiredCapabilities?: KnownPublishRequiredCapability[];
   source: string;
   spaces: PublishArtifactSpace[];
   version: 1;
@@ -132,6 +168,7 @@ export interface PublishArtifactV1 {
 export interface PublishArtifactV2 {
   egressLineage: EgressLineage;
   exportedAt: string;
+  requiredCapabilities?: KnownPublishRequiredCapability[];
   source: string;
   spaces: EncryptedPublishArtifactSpace[];
   version: 2;
@@ -406,17 +443,22 @@ export const buildPublishArtifact = (input: {
 export const buildEncryptedPublishArtifact = (input: {
   egressLineage?: EgressLineage;
   encryptedPayload: EncryptedArtifactPayload;
+  requiredCapabilities?: KnownPublishRequiredCapability[];
   routeSlug: string;
   secretToken: string;
   sourceType: "note" | "collection";
 }): PublishArtifactV2 => {
-  const { egressLineage: providedLineage, ...encryptedInput } = input;
+  const {
+    egressLineage: providedLineage,
+    requiredCapabilities,
+    ...encryptedInput
+  } = input;
   const validated = validateAndProjectEncryptedPublishInput(encryptedInput);
   const egressLineage = egressLineageSchema.parse(
     providedLineage ?? legacyLocalOnlyEgressLineage("legacy")
   );
   const exportedAt = requirePublishDateTime(new Date().toISOString());
-  return {
+  const artifact: PublishArtifactV2 = {
     egressLineage,
     exportedAt,
     source: validated.routeSlug,
@@ -431,6 +473,11 @@ export const buildEncryptedPublishArtifact = (input: {
     ],
     version: 2,
   };
+  // Capability is declared on the outer envelope; plaintext assets stay inside ciphertext.
+  if (requiredCapabilities && requiredCapabilities.length > 0) {
+    artifact.requiredCapabilities = [...requiredCapabilities];
+  }
+  return artifact;
 };
 
 export const derivePublishArtifactFilename = (artifact: PublishArtifact) => {

package/src/publish/attachment-bundle.ts

@@ -0,0 +1,145 @@
+/**
+ * Deterministic asset descriptor assembly and egress size accounting.
+ *
+ * @module src/publish/attachment-bundle
+ */
+
+import type { PublishArtifactV1 } from "./artifact";
+import type {
+  AttachmentDiagnostic,
+  PendingAssetPayload,
+  PublishAssetEgressSummary,
+} from "./attachment-types";
+
+import { measureArtifactUploadBytes } from "./artifact-asset-codec";
+import {
+  BUNDLED_RASTER_ASSETS_CAPABILITY,
+  MAX_PUBLISH_UPLOAD_BYTES,
+  type PublishArtifactAsset,
+  type PublishArtifactAssetReference,
+} from "./artifact-asset-contract";
+
+const compareCodeUnits = (left: string, right: string): number => {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+};
+
+const sortReferences = (
+  references: PublishArtifactAssetReference[]
+): PublishArtifactAssetReference[] =>
+  [...references].sort(
+    (a, b) =>
+      compareCodeUnits(a.noteSlug, b.noteSlug) ||
+      compareCodeUnits(a.sourceRef, b.sourceRef)
+  );
+
+/** Merge pending payloads across notes into deterministic asset descriptors. */
+export function buildDeterministicAssets(
+  payloads: Map<string, PendingAssetPayload>
+): PublishArtifactAsset[] {
+  const assets: PublishArtifactAsset[] = [];
+  for (const id of [...payloads.keys()].sort(compareCodeUnits)) {
+    const payload = payloads.get(id);
+    if (!payload) continue;
+    const references = sortReferences(payload.references);
+    const seen = new Set<string>();
+    const uniqueRefs: PublishArtifactAssetReference[] = [];
+    for (const reference of references) {
+      const key = `${reference.noteSlug}\0${reference.sourceRef}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      uniqueRefs.push(reference);
+    }
+    assets.push({
+      byteLength: payload.byteLength,
+      data: payload.data,
+      encoding: "base64",
+      height: payload.height,
+      id: payload.sha256,
+      mediaType: payload.mediaType,
+      references: uniqueRefs,
+      sha256: payload.sha256,
+      width: payload.width,
+    });
+  }
+  return assets;
+}
+
+export function attachAssetsToV1Artifact(
+  artifact: PublishArtifactV1,
+  assets: PublishArtifactAsset[]
+): PublishArtifactV1 {
+  if (assets.length === 0) {
+    const { assets: _assets, requiredCapabilities: _caps, ...rest } = artifact;
+    return rest;
+  }
+  return {
+    ...artifact,
+    assets,
+    requiredCapabilities: [BUNDLED_RASTER_ASSETS_CAPABILITY],
+  };
+}
+
+export function summarizeAssetEgress(input: {
+  /** Optional override when assets live only inside encrypted plaintext. */
+  assets?: PublishArtifactAsset[];
+  artifact: unknown;
+  diagnostics: AttachmentDiagnostic[];
+  externalCount: number;
+  preDedupRawBytes: number;
+}): PublishAssetEgressSummary {
+  const record =
+    input.artifact && typeof input.artifact === "object"
+      ? (input.artifact as { assets?: PublishArtifactAsset[] })
+      : {};
+  const assets =
+    input.assets ?? (Array.isArray(record.assets) ? record.assets : []);
+  const rawBytes = assets.reduce((sum, asset) => sum + asset.byteLength, 0);
+  const encodedBytes = assets.reduce(
+    (sum, asset) => sum + asset.data.length,
+    0
+  );
+  const referenceCount = assets.reduce(
+    (sum, asset) => sum + asset.references.length,
+    0
+  );
+  const finalUploadBytes = measureArtifactUploadBytes(input.artifact);
+  if (finalUploadBytes > MAX_PUBLISH_UPLOAD_BYTES) {
+    throw new Error(
+      `ENVELOPE_OVERSIZE: final serialized upload is ${finalUploadBytes} bytes; max is ${MAX_PUBLISH_UPLOAD_BYTES}`
+    );
+  }
+  const diagnostics = [...input.diagnostics].sort(
+    (a, b) =>
+      compareCodeUnits(a.code, b.code) ||
+      compareCodeUnits(a.noteSlug, b.noteSlug) ||
+      compareCodeUnits(a.sourceRef, b.sourceRef) ||
+      compareCodeUnits(a.message, b.message)
+  );
+  return {
+    assetCount: assets.length,
+    dedupSavedBytes: Math.max(0, input.preDedupRawBytes - rawBytes),
+    diagnostics,
+    encodedBytes,
+    externalCount: input.externalCount,
+    finalUploadBytes,
+    rawBytes,
+    referenceCount,
+  };
+}
+
+export function emptyAssetEgressSummary(
+  finalUploadBytes = 0
+): PublishAssetEgressSummary {
+  return {
+    assetCount: 0,
+    dedupSavedBytes: 0,
+    diagnostics: [],
+    encodedBytes: 0,
+    externalCount: 0,
+    finalUploadBytes,
+    rawBytes: 0,
+    referenceCount: 0,
+  };
+}