@forgeax/engine-import 0.1.23 → 0.1.25

package/src/source-package-publication.ts

@@ -1,7 +1,8 @@
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { mkdir, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
 import {
+  type DdcArtifact,
   type DdcEntry,
   type DdcGenerationEntryCandidate,
   DdcGenerationSession,
@@ -9,6 +10,7 @@ import {
   DdcLifecycle,
   ddcOutputDigest,
 } from '@forgeax/engine-ddc';
+import { canonicalDdcJson } from '@forgeax/engine-ddc/key';
 import {
   type CatalogEntry,
   err,
@@ -45,9 +47,17 @@ export interface ImportPublicationInput {
   readonly transport?: {
     readonly path: string;
     readonly body: string;
+    /** Complete package-relative artifact closure for the published Pack. */
+    readonly artifacts?: readonly ImportPublicationArtifact[];
   };
 }
 
+export interface ImportPublicationArtifact {
+  readonly path: string;
+  readonly mediaType: string;
+  readonly bytes: Uint8Array;
+}
+
 export interface ImportPublicationError {
   readonly code: SourcePackageError['code'];
   readonly expected: string;
@@ -184,6 +194,225 @@ function importPublicationFailure(error: SourcePackageError): ImportPublicationE
   };
 }
 
+function publicationArtifacts(
+  transport: ImportPublicationInput['transport'],
+): Readonly<Record<string, DdcArtifact>> {
+  return Object.fromEntries(
+    (transport?.artifacts ?? []).map((artifact) => [
+      artifact.path,
+      { mediaType: artifact.mediaType, bytes: artifact.bytes },
+    ]),
+  );
+}
+
+function publicationContext(input: ImportPublicationInput): SourcePackageErrorContext {
+  return {
+    sourceMeta: '<import-publication>',
+    anchorGuid: input.guid,
+    affectedGuids: input.publishedGuids,
+    producer: 'source-package/import-publication',
+    importer: 'import-publication',
+  };
+}
+
+/**
+ * Validate the Pack-to-transport closure before DDC staging can advance its
+ * head. The Pack is the authority for required artifact paths; a missing or
+ * mismatched body must never become a published `current` generation.
+ */
+function validatePublicationArtifactClosure(
+  input: ImportPublicationInput,
+): Result<Readonly<Record<string, DdcArtifact>>, SourcePackageError> {
+  const context = publicationContext(input);
+  const pack = input.pack;
+  if (
+    pack === null ||
+    typeof pack !== 'object' ||
+    (pack as { readonly schemaVersion?: unknown }).schemaVersion !== '2.0.0' ||
+    (pack as { readonly kind?: unknown }).kind !== 'internal-text-package'
+  ) {
+    return ok(publicationArtifacts(input.transport));
+  }
+  const assets = (pack as { readonly assets?: unknown }).assets;
+  if (!Array.isArray(assets)) {
+    return err(
+      sourcePackageError('source-package-publication-invalid', context, {
+        stage: 'route-integrity',
+        reason: 'published Pack does not contain an assets array',
+      }),
+    );
+  }
+
+  const required = new Map<
+    string,
+    {
+      readonly mediaType?: string;
+      readonly byteLength?: number;
+      readonly integrity?: { readonly algorithm: string; readonly digest: string };
+    }
+  >();
+  for (const asset of assets) {
+    if (asset === null || typeof asset !== 'object') {
+      return err(
+        sourcePackageError('source-package-publication-invalid', context, {
+          stage: 'route-integrity',
+          reason: 'published Pack contains a non-object asset row',
+        }),
+      );
+    }
+    const rawArtifacts = (asset as { readonly artifacts?: unknown }).artifacts;
+    if (rawArtifacts === undefined) continue;
+    if (rawArtifacts === null || typeof rawArtifacts !== 'object' || Array.isArray(rawArtifacts)) {
+      return err(
+        sourcePackageError('source-package-publication-invalid', context, {
+          stage: 'route-integrity',
+          reason: 'published Pack contains an invalid asset artifact map',
+        }),
+      );
+    }
+    for (const [localKey, rawDescriptor] of Object.entries(
+      rawArtifacts as Record<string, unknown>,
+    )) {
+      if (rawDescriptor === null || typeof rawDescriptor !== 'object') {
+        return err(
+          sourcePackageError('source-package-publication-invalid', context, {
+            stage: 'route-integrity',
+            reason: `artifact descriptor ${localKey} is not an object`,
+          }),
+        );
+      }
+      const descriptor = rawDescriptor as Record<string, unknown>;
+      const path = descriptor.path;
+      if (typeof path !== 'string' || path.length === 0) {
+        return err(
+          sourcePackageError('source-package-publication-invalid', context, {
+            stage: 'route-integrity',
+            reason: `artifact descriptor ${localKey} has no package-relative path`,
+          }),
+        );
+      }
+      const mediaType = descriptor.mediaType;
+      const byteLength = descriptor.byteLength;
+      const integrityValue = descriptor.integrity;
+      const integrity =
+        integrityValue !== null && typeof integrityValue === 'object'
+          ? {
+              algorithm: (integrityValue as { readonly algorithm?: unknown }).algorithm,
+              digest: (integrityValue as { readonly digest?: unknown }).digest,
+            }
+          : undefined;
+      if (
+        (mediaType !== undefined && typeof mediaType !== 'string') ||
+        (byteLength !== undefined &&
+          (!Number.isSafeInteger(byteLength) || (byteLength as number) < 0)) ||
+        (integrityValue !== undefined &&
+          (integrity === undefined ||
+            typeof integrity.algorithm !== 'string' ||
+            typeof integrity.digest !== 'string'))
+      ) {
+        return err(
+          sourcePackageError('source-package-publication-invalid', context, {
+            stage: 'route-integrity',
+            reason: `artifact descriptor ${path} has invalid metadata`,
+          }),
+        );
+      }
+      if (required.has(path)) {
+        return err(
+          sourcePackageError('source-package-publication-invalid', context, {
+            stage: 'route-integrity',
+            reason: `artifact path ${path} is declared more than once`,
+          }),
+        );
+      }
+      required.set(path, {
+        ...(typeof mediaType === 'string' ? { mediaType } : {}),
+        ...(typeof byteLength === 'number' ? { byteLength } : {}),
+        ...(integrity !== undefined &&
+        typeof integrity.algorithm === 'string' &&
+        typeof integrity.digest === 'string'
+          ? { integrity: { algorithm: integrity.algorithm, digest: integrity.digest } }
+          : {}),
+      });
+    }
+  }
+
+  const available = new Map<string, ImportPublicationArtifact>();
+  const duplicatePaths: string[] = [];
+  for (const artifact of input.transport?.artifacts ?? []) {
+    if (available.has(artifact.path)) duplicatePaths.push(artifact.path);
+    available.set(artifact.path, artifact);
+  }
+  const missing: string[] = [];
+  const mismatched: string[] = [...duplicatePaths.map((path) => `${path}: duplicate body`)];
+  for (const path of available.keys()) {
+    if (!required.has(path)) mismatched.push(`${path}: unexpected body`);
+  }
+  for (const [path, descriptor] of required) {
+    const artifact = available.get(path);
+    if (artifact === undefined) {
+      missing.push(path);
+      continue;
+    }
+    if (!(artifact.bytes instanceof Uint8Array)) {
+      mismatched.push(`${path}: body is not Uint8Array`);
+      continue;
+    }
+    if (descriptor.mediaType !== undefined && artifact.mediaType !== descriptor.mediaType) {
+      mismatched.push(`${path}: media type mismatch`);
+    }
+    if (
+      descriptor.byteLength !== undefined &&
+      artifact.bytes.byteLength !== descriptor.byteLength
+    ) {
+      mismatched.push(`${path}: byte length mismatch`);
+    }
+    if (descriptor.integrity !== undefined) {
+      const actualDigest = `sha256:${createHash('sha256').update(artifact.bytes).digest('hex')}`;
+      if (
+        descriptor.integrity.algorithm !== 'sha256' ||
+        descriptor.integrity.digest !== actualDigest
+      ) {
+        mismatched.push(`${path}: integrity mismatch`);
+      }
+    }
+  }
+  if (missing.length > 0 || mismatched.length > 0) {
+    return err(
+      sourcePackageError('source-package-publication-invalid', context, {
+        stage: 'route-integrity',
+        reason: 'Pack artifact closure is incomplete or mismatched',
+        ...(missing.length === 0 ? {} : { missing }),
+        ...(mismatched.length === 0 ? {} : { unexpected: mismatched }),
+      }),
+    );
+  }
+
+  if (input.transport !== undefined) {
+    let transportedPack: unknown;
+    try {
+      transportedPack = JSON.parse(input.transport.body) as unknown;
+    } catch {
+      return err(
+        sourcePackageError('source-package-publication-invalid', context, {
+          stage: 'route-integrity',
+          reason: 'transport body is not valid JSON for the published Pack',
+        }),
+      );
+    }
+    if (canonicalDdcJson(transportedPack) !== canonicalDdcJson(pack)) {
+      return err(
+        sourcePackageError('source-package-publication-invalid', context, {
+          stage: 'route-integrity',
+          reason: 'transport body does not match the published Pack',
+        }),
+      );
+    }
+  }
+
+  return ok(publicationArtifacts(input.transport));
+}
+
 function projectImportPublication(
   input: ImportPublicationInput,
   head: DdcHead,
@@ -231,6 +460,15 @@ export async function publishImportPublication(
 export async function stageImportPublication(
   input: ImportPublicationInput,
 ): Promise<StagedImportPublicationResult> {
+  const validatedArtifacts = validatePublicationArtifactClosure(input);
+  if (!validatedArtifacts.ok) {
+    return {
+      ok: false,
+      error: importPublicationFailure(validatedArtifacts.error),
+      head: await inspectHead(input.root, input.guid, input.desiredKey),
+    };
+  }
+  const artifacts = validatedArtifacts.value;
   const staged = await stageSourcePackageDdc({
     root: input.root,
     entry: {
@@ -238,7 +476,7 @@ export async function stageImportPublication(
       guid: input.guid,
       payload: input.pack,
       refs: [],
-      artifacts: {},
+      artifacts,
       receipt: {
         guid: input.guid,
         key: input.desiredKey,
@@ -248,17 +486,11 @@ export async function stageImportPublication(
           guid: input.guid,
           payload: input.pack,
           refs: [],
-          artifacts: {},
+          artifacts,
         }),
       },
     },
-    context: {
-      sourceMeta: '<import-publication>',
-      anchorGuid: input.guid,
-      affectedGuids: input.publishedGuids,
-      producer: 'source-package/import-publication',
-      importer: 'import-publication',
-    },
+    context: publicationContext(input),
   });
   if (!staged.ok) {
     return {

package/dist/__tests__/parameterized-scriptable-pack.unit.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=parameterized-scriptable-pack.unit.test.d.ts.map

package/dist/__tests__/parameterized-scriptable-pack.unit.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"parameterized-scriptable-pack.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/parameterized-scriptable-pack.unit.test.ts"],"names":[],"mappings":""}

package/dist/parameterized-scriptable-pack.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"parameterized-scriptable-pack.d.ts","sourceRoot":"","sources":["../src/parameterized-scriptable-pack.ts"],"names":[],"mappings":"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"}