@gmickel/gno 1.20.0 → 1.22.0

package/src/publish/artifact-validation.ts

@@ -0,0 +1,259 @@
+/**
+ * Runtime validation and closed projection for publish artifact builders.
+ *
+ * @module src/publish/artifact-validation
+ */
+
+export const MAX_PUBLISH_SLUG_LENGTH = 80;
+export const MAX_ENCRYPTED_CIPHERTEXT_BASE64_LENGTH = 67_108_864;
+export const MAX_ENCRYPTED_KEY_MATERIAL_BASE64_LENGTH = 1024;
+export const MAX_ENCRYPTED_SECRET_TOKEN_LENGTH = 512;
+
+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;
+
+const SOURCE_TYPES = new Set(["collection", "note"]);
+const READER_VISIBILITIES = new Set(["invite-only", "public", "secret-link"]);
+
+export interface ValidatedPublishNote {
+  markdown: string;
+  metadata?: Record<string, string | string[]>;
+  slug: string;
+  summary: string;
+  title: string;
+}
+
+export interface ValidatedPublishSpaceInput {
+  homeNoteSlug?: string;
+  notes: ValidatedPublishNote[];
+  routeSlug: string;
+  sourceType: "note" | "collection";
+  summary: string;
+  title: string;
+  visibility: "invite-only" | "public" | "secret-link";
+}
+
+export interface ValidatedEncryptedPublishInput {
+  encryptedPayload: {
+    ciphertext: string;
+    iterations: number;
+    iv: string;
+    salt: string;
+  };
+  routeSlug: string;
+  secretToken: string;
+  sourceType: "note" | "collection";
+}
+
+const requireRecord = (
+  value: unknown,
+  field: string
+): Record<string, unknown> => {
+  if (!(value && typeof value === "object" && !Array.isArray(value))) {
+    throw new Error(`${field} must be an object`);
+  }
+  return value as Record<string, unknown>;
+};
+
+const requireString = (value: unknown, field: string): string => {
+  if (typeof value !== "string") {
+    throw new Error(`${field} must be a string`);
+  }
+  return value;
+};
+
+const requireNonblankString = (value: unknown, field: string): string => {
+  const result = requireString(value, field);
+  if (result.trim().length === 0) {
+    throw new Error(`${field} must not be blank`);
+  }
+  return result;
+};
+
+const requireBoundedNonblankString = (
+  value: unknown,
+  field: string,
+  maxLength: number
+): string => {
+  const result = requireNonblankString(value, field);
+  if (result.length > maxLength) {
+    throw new Error(`${field} must not exceed ${maxLength} characters`);
+  }
+  return result;
+};
+
+const requireBase64 = (
+  value: unknown,
+  field: string,
+  maxLength: number
+): string => {
+  const result = requireBoundedNonblankString(value, field, maxLength);
+  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)) {
+    throw new Error(`${field} must be a valid publish slug`);
+  }
+  return result;
+};
+
+const projectMetadata = (
+  value: unknown,
+  field: string
+): Record<string, string | string[]> | undefined => {
+  if (value === undefined) return undefined;
+
+  const input = requireRecord(value, field);
+  const result: Record<string, string | string[]> = {};
+  for (const [key, entry] of Object.entries(input)) {
+    if (typeof entry === "string") {
+      result[key] = entry;
+      continue;
+    }
+    if (
+      Array.isArray(entry) &&
+      entry.every((item): item is string => typeof item === "string")
+    ) {
+      result[key] = [...entry];
+      continue;
+    }
+    throw new Error(`${field}.${key} must be a string or string array`);
+  }
+  return result;
+};
+
+const projectNote = (value: unknown, index: number): ValidatedPublishNote => {
+  const field = `notes[${index}]`;
+  const input = requireRecord(value, field);
+  const metadata = projectMetadata(input.metadata, `${field}.metadata`);
+  const note: ValidatedPublishNote = {
+    markdown: requireString(input.markdown, `${field}.markdown`),
+    slug: requireSlug(input.slug, `${field}.slug`),
+    summary: requireString(input.summary, `${field}.summary`),
+    title: requireNonblankString(input.title, `${field}.title`),
+  };
+  if (metadata !== undefined) note.metadata = metadata;
+  return note;
+};
+
+export const validateAndProjectPublishSpaceInput = (
+  value: unknown
+): ValidatedPublishSpaceInput => {
+  const input = requireRecord(value, "publish input");
+  if (!Array.isArray(input.notes) || input.notes.length === 0) {
+    throw new Error("Publish input must contain at least one note");
+  }
+
+  const notes = input.notes.map(projectNote);
+  const noteSlugs = new Set<string>();
+  for (const note of notes) {
+    if (noteSlugs.has(note.slug)) {
+      throw new Error(
+        `Publish input contains duplicate note slug "${note.slug}"`
+      );
+    }
+    noteSlugs.add(note.slug);
+  }
+
+  const routeSlug = requireSlug(input.routeSlug, "routeSlug");
+  const sourceType = requireString(input.sourceType, "sourceType");
+  if (!SOURCE_TYPES.has(sourceType)) {
+    throw new Error('sourceType must be "note" or "collection"');
+  }
+
+  const visibility = requireString(input.visibility, "visibility");
+  if (!READER_VISIBILITIES.has(visibility)) {
+    throw new Error(
+      'visibility must be "public", "secret-link", or "invite-only"'
+    );
+  }
+
+  const homeNoteSlug =
+    input.homeNoteSlug === undefined
+      ? undefined
+      : requireSlug(input.homeNoteSlug, "homeNoteSlug");
+  if (homeNoteSlug !== undefined && !noteSlugs.has(homeNoteSlug)) {
+    throw new Error(`homeNoteSlug "${homeNoteSlug}" is not present in notes`);
+  }
+
+  const result: ValidatedPublishSpaceInput = {
+    notes,
+    routeSlug,
+    sourceType: sourceType as "note" | "collection",
+    summary: requireString(input.summary, "summary"),
+    title: requireNonblankString(input.title, "title"),
+    visibility: visibility as ValidatedPublishSpaceInput["visibility"],
+  };
+  if (homeNoteSlug !== undefined) result.homeNoteSlug = homeNoteSlug;
+  return result;
+};
+
+export const validateAndProjectEncryptedPublishInput = (
+  value: unknown
+): ValidatedEncryptedPublishInput => {
+  const input = requireRecord(value, "encrypted publish input");
+  const payload = requireRecord(input.encryptedPayload, "encryptedPayload");
+  const iterations = payload.iterations;
+  if (
+    typeof iterations !== "number" ||
+    !Number.isSafeInteger(iterations) ||
+    iterations <= 0
+  ) {
+    throw new Error(
+      "encryptedPayload.iterations must be a positive safe integer"
+    );
+  }
+
+  const sourceType = requireString(input.sourceType, "sourceType");
+  if (!SOURCE_TYPES.has(sourceType)) {
+    throw new Error('sourceType must be "note" or "collection"');
+  }
+
+  return {
+    encryptedPayload: {
+      ciphertext: requireBase64(
+        payload.ciphertext,
+        "encryptedPayload.ciphertext",
+        MAX_ENCRYPTED_CIPHERTEXT_BASE64_LENGTH
+      ),
+      iterations,
+      iv: requireBase64(
+        payload.iv,
+        "encryptedPayload.iv",
+        MAX_ENCRYPTED_KEY_MATERIAL_BASE64_LENGTH
+      ),
+      salt: requireBase64(
+        payload.salt,
+        "encryptedPayload.salt",
+        MAX_ENCRYPTED_KEY_MATERIAL_BASE64_LENGTH
+      ),
+    },
+    routeSlug: requireSlug(input.routeSlug, "routeSlug"),
+    secretToken: requireBoundedNonblankString(
+      input.secretToken,
+      "secretToken",
+      MAX_ENCRYPTED_SECRET_TOKEN_LENGTH
+    ),
+    sourceType: sourceType as "note" | "collection",
+  };
+};
+
+export const requirePublishDateTime = (
+  value: unknown,
+  field = "exportedAt"
+): string => {
+  const result = requireString(value, field);
+  if (
+    !/^\d{4}-\d{2}-\d{2}T/u.test(result) ||
+    Number.isNaN(Date.parse(result))
+  ) {
+    throw new Error(`${field} must be a valid date-time`);
+  }
+  return result;
+};

package/src/publish/artifact.ts

@@ -4,9 +4,23 @@
  * @module src/publish/artifact
  */
 
-import type { DocumentRow, TagRow } from "../store/types";
+import type { DocumentRow } from "../store/types";
 
+import { deriveDocid } from "../app/constants";
+import {
+  contextCapsuleEvidenceIdentity,
+  sha256Text,
+} from "../core/context-capsule-validation";
 import { stripFrontmatter } from "../ingestion/frontmatter";
+import {
+  MAX_PUBLISH_SLUG_LENGTH,
+  requirePublishDateTime,
+  validateAndProjectEncryptedPublishInput,
+  validateAndProjectPublishSpaceInput,
+} from "./artifact-validation";
+
+export { MAX_PUBLISH_SLUG_LENGTH } from "./artifact-validation";
+export { buildExportedMetadata } from "./metadata";
 
 export type PublishVisibility =
   | "encrypted"
@@ -22,16 +36,70 @@ export interface PublishArtifactNote {
   title: string;
 }
 
-export interface PublishArtifactSpace {
+export const PUBLIC_PUBLISH_MANIFEST_SCHEMA_VERSION = "1.0" as const;
+
+export const PUBLIC_PUBLISH_CAPABILITIES = {
+  capsuleEvidence: true,
+  exactLineCitations: true,
+  llmsTxt: true,
+  markdownDocuments: true,
+} as const;
+
+export interface PublicPublishEvidence {
+  docid: string;
+  endLine: number;
+  evidenceId: string;
+  locator: string;
+  mirrorHash: string;
+  passageHash: string;
+  sourceHash: string;
+  startLine: number;
+  uri: string;
+}
+
+export interface PublicPublishDocument {
+  byteLength: number;
+  contentHash: string;
+  evidence: PublicPublishEvidence;
+  lineCount: number;
+  markdownPath: string;
+  slug: string;
+  summary: string;
+  title: string;
+}
+
+export interface PublicPublishManifest {
+  capabilities: typeof PUBLIC_PUBLISH_CAPABILITIES;
+  documents: PublicPublishDocument[];
+  generatedAt: string;
+  projectionRevision: string;
+  schemaVersion: typeof PUBLIC_PUBLISH_MANIFEST_SCHEMA_VERSION;
+  visibility: "public";
+}
+
+interface PublishArtifactSpaceBase {
   homeNoteSlug?: string;
   notes: PublishArtifactNote[];
   routeSlug: string;
   sourceType: "note" | "collection";
   summary: string;
   title: string;
-  visibility: PublishVisibility;
 }
 
+export interface PublicPublishArtifactSpace extends PublishArtifactSpaceBase {
+  manifest: PublicPublishManifest;
+  visibility: "public";
+}
+
+export interface RestrictedPublishArtifactSpace extends PublishArtifactSpaceBase {
+  manifest?: never;
+  visibility: "invite-only" | "secret-link";
+}
+
+export type PublishArtifactSpace =
+  | PublicPublishArtifactSpace
+  | RestrictedPublishArtifactSpace;
+
 export interface EncryptedArtifactPayload {
   ciphertext: string;
   iterations: number;
@@ -70,29 +138,6 @@ export const PUBLISH_VISIBILITY_VALUES = [
   "encrypted",
 ] as const;
 
-export const MAX_PUBLISH_SLUG_LENGTH = 80;
-
-const ALLOWED_FRONTMATTER_METADATA_KEYS = new Set([
-  "audience",
-  "canonical",
-  "canonicalUrl",
-  "canonicalURL",
-  "coverAlt",
-  "coverImage",
-  "icon",
-  "image",
-  "layout",
-  "publishedAt",
-  "readingTime",
-  "series",
-  "seriesOrder",
-  "status",
-  "subtitle",
-  "theme",
-  "topic",
-  "topics",
-]);
-
 export const isPublishVisibility = (
   value: unknown
 ): value is PublishVisibility =>
@@ -175,119 +220,190 @@ export const deriveExportedSummary = (
   return plain.slice(0, 200).trim();
 };
 
-export const buildExportedMetadata = (
-  doc: Pick<
-    DocumentRow,
-    | "author"
-    | "categories"
-    | "collection"
-    | "contentType"
-    | "frontmatterDate"
-    | "languageHint"
-    | "relPath"
-  >,
-  parsedFrontmatter: Record<string, unknown>,
-  tags: TagRow[]
-) => {
-  const metadata: Record<string, string | string[]> = {};
+const compareCodeUnits = (left: string, right: string): number => {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+};
 
-  if (doc.author) {
-    metadata.author = doc.author;
-  }
-  if (doc.contentType) {
-    metadata.contentType = doc.contentType;
-  }
-  if (doc.languageHint) {
-    metadata.language = doc.languageHint;
-  }
-  if (doc.frontmatterDate) {
-    metadata.date = doc.frontmatterDate;
+const canonicalizeJsonValue = (value: unknown): unknown => {
+  if (Array.isArray(value)) {
+    return value.map(canonicalizeJsonValue);
   }
-  if (doc.categories?.length) {
-    metadata.categories = doc.categories;
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value)
+        .sort(([left], [right]) => compareCodeUnits(left, right))
+        .map(([key, entry]) => [key, canonicalizeJsonValue(entry)])
+    );
   }
+  return value;
+};
 
-  const tagValues = tags.map((tag) => tag.tag);
-  if (tagValues.length) {
-    metadata.tags = tagValues;
-  }
+const canonicalJson = (value: unknown): string =>
+  JSON.stringify(canonicalizeJsonValue(value));
+
+const buildPublicPublishDocument = (
+  routeSlug: string,
+  note: PublishArtifactNote
+): PublicPublishDocument => {
+  const contentHash = sha256Text(note.markdown);
+  const docid = deriveDocid(contentHash);
+  const lineCount = note.markdown.split("\n").length;
+  const markdownPath = `./${note.slug}.md`;
+  const uri = `gno://public/${routeSlug}/${note.slug}.md`;
+  const evidenceBase = {
+    uri,
+    docid,
+    startLine: 1,
+    endLine: lineCount,
+    sourceHash: contentHash,
+    mirrorHash: contentHash,
+    passageHash: contentHash,
+  };
+
+  return {
+    byteLength: new TextEncoder().encode(note.markdown).byteLength,
+    contentHash,
+    evidence: {
+      ...evidenceBase,
+      evidenceId: contextCapsuleEvidenceIdentity(evidenceBase),
+      locator: `${markdownPath}#L1-L${lineCount}`,
+    },
+    lineCount,
+    markdownPath,
+    slug: note.slug,
+    summary: note.summary,
+    title: note.title,
+  };
+};
 
-  metadata.collection = doc.collection;
-  metadata.sourceRelPath = doc.relPath;
-
-  for (const [key, value] of Object.entries(parsedFrontmatter)) {
-    if (
-      key === "tags" ||
-      key === "title" ||
-      key === "summary" ||
-      !ALLOWED_FRONTMATTER_METADATA_KEYS.has(key)
-    ) {
-      continue;
-    }
-    if (typeof value === "string" && value.trim()) {
-      metadata[key] = value.trim();
-      continue;
-    }
-    if (Array.isArray(value)) {
-      const cleaned = value
-        .filter((entry): entry is string => typeof entry === "string")
-        .map((entry) => entry.trim())
-        .filter(Boolean);
-      if (cleaned.length > 0) {
-        metadata[key] = cleaned;
-      }
-    }
+export const buildPublicPublishManifest = (input: {
+  exportedAt: string;
+  homeNoteSlug?: string;
+  notes: PublishArtifactNote[];
+  routeSlug: string;
+  sourceType: "note" | "collection";
+  summary: string;
+  title: string;
+  visibility: "public";
+}): PublicPublishManifest => {
+  const validated = validateAndProjectPublishSpaceInput(input);
+  if (validated.visibility !== "public") {
+    throw new Error("Public publish manifests require public visibility");
   }
-
-  return metadata;
+  const exportedAt = requirePublishDateTime(input.exportedAt);
+  const documents = validated.notes
+    .map((note) => buildPublicPublishDocument(validated.routeSlug, note))
+    .sort(
+      (left, right) =>
+        compareCodeUnits(left.slug, right.slug) ||
+        compareCodeUnits(left.title, right.title) ||
+        compareCodeUnits(left.contentHash, right.contentHash)
+    );
+  const revisionProjection = {
+    capabilities: PUBLIC_PUBLISH_CAPABILITIES,
+    documents,
+    homeNoteSlug: validated.homeNoteSlug ?? null,
+    notes: validated.notes
+      .map((note) => ({
+        markdown: note.markdown,
+        metadata: note.metadata ?? {},
+        slug: note.slug,
+        summary: note.summary,
+        title: note.title,
+      }))
+      .sort((left, right) => compareCodeUnits(left.slug, right.slug)),
+    routeSlug: validated.routeSlug,
+    sourceType: validated.sourceType,
+    summary: validated.summary,
+    title: validated.title,
+    visibility: validated.visibility,
+  };
+
+  return {
+    capabilities: { ...PUBLIC_PUBLISH_CAPABILITIES },
+    documents,
+    generatedAt: exportedAt,
+    projectionRevision: sha256Text(canonicalJson(revisionProjection)),
+    schemaVersion: PUBLIC_PUBLISH_MANIFEST_SCHEMA_VERSION,
+    visibility: validated.visibility,
+  };
 };
 
 export const buildPublishArtifact = (input: {
   homeNoteSlug?: string;
   notes: PublishArtifactNote[];
   routeSlug: string;
-  source: string;
   sourceType: "note" | "collection";
   summary: string;
   title: string;
-  visibility: PublishVisibility;
-}) => ({
-  exportedAt: new Date().toISOString(),
-  source: input.source,
-  spaces: [
-    {
-      homeNoteSlug: input.homeNoteSlug,
-      notes: input.notes,
-      routeSlug: input.routeSlug,
-      sourceType: input.sourceType,
-      summary: input.summary,
-      title: input.title,
-      visibility: input.visibility,
-    },
-  ],
-  version: 1 as const,
-});
+  visibility: Exclude<PublishVisibility, "encrypted">;
+}): PublishArtifactV1 => {
+  const validated = validateAndProjectPublishSpaceInput(input);
+  const exportedAt = new Date().toISOString();
+  const base = {
+    ...(validated.homeNoteSlug === undefined
+      ? {}
+      : { homeNoteSlug: validated.homeNoteSlug }),
+    notes: validated.notes,
+    routeSlug: validated.routeSlug,
+    sourceType: validated.sourceType,
+    summary: validated.summary,
+    title: validated.title,
+  };
+  const space: PublishArtifactSpace =
+    validated.visibility === "public"
+      ? {
+          ...base,
+          manifest: buildPublicPublishManifest({
+            exportedAt,
+            homeNoteSlug: validated.homeNoteSlug,
+            notes: validated.notes,
+            routeSlug: validated.routeSlug,
+            sourceType: validated.sourceType,
+            summary: validated.summary,
+            title: validated.title,
+            visibility: validated.visibility,
+          }),
+          visibility: validated.visibility,
+        }
+      : {
+          ...base,
+          visibility: validated.visibility,
+        };
+
+  return {
+    exportedAt,
+    source: validated.routeSlug,
+    spaces: [space],
+    version: 1,
+  };
+};
 
 export const buildEncryptedPublishArtifact = (input: {
   encryptedPayload: EncryptedArtifactPayload;
   routeSlug: string;
   secretToken: string;
-  source: string;
   sourceType: "note" | "collection";
-}) => ({
-  exportedAt: new Date().toISOString(),
-  source: input.source,
-  spaces: [
-    {
-      encryptedPayload: input.encryptedPayload,
-      routeSlug: input.routeSlug,
-      secretToken: input.secretToken,
-      sourceType: input.sourceType,
-      visibility: "encrypted" as const,
-    },
-  ],
-  version: 2 as const,
-});
+}): PublishArtifactV2 => {
+  const validated = validateAndProjectEncryptedPublishInput(input);
+  const exportedAt = requirePublishDateTime(new Date().toISOString());
+  return {
+    exportedAt,
+    source: validated.routeSlug,
+    spaces: [
+      {
+        encryptedPayload: validated.encryptedPayload,
+        routeSlug: validated.routeSlug,
+        secretToken: validated.secretToken,
+        sourceType: validated.sourceType,
+        visibility: "encrypted",
+      },
+    ],
+    version: 2,
+  };
+};
 
 export const derivePublishArtifactFilename = (artifact: PublishArtifact) => {
   const routeSlug =