@aikdna/kdna-core 0.17.0 → 0.18.0

package/src/v1/index.js

@@ -228,9 +228,13 @@ function detectContainerFormat(absPath) {
  * truncated input.
  */
 function listZipEntries(absPath, opts = {}) {
+  return listZipEntriesFromBuffer(fs.readFileSync(absPath), opts);
+}
+
+function listZipEntriesFromBuffer(input, opts = {}) {
   const secure = opts.secure !== false;
   const limits = { ...DEFAULT_CONTAINER_LIMITS, ...(opts.limits || {}) };
-  const buf = fs.readFileSync(absPath);
+  const buf = Buffer.isBuffer(input) ? input : Buffer.from(input);
   if (secure && buf.length > limits.maxContainerBytes) {
     throw new Error(`container exceeds maximum size (${limits.maxContainerBytes} bytes)`);
   }
@@ -533,6 +537,7 @@ function readV1Layout(absPath) {
   const map = {};
   let entries = null; // ZIP entries if container
   let kind; // 'dir' | 'file'
+  let containerBytes = null;
 
   if (stat.isDirectory()) {
     kind = 'dir';
@@ -558,13 +563,10 @@ function readV1Layout(absPath) {
     }
   } else if (stat.isFile()) {
     kind = 'file';
-    entries = listZipEntries(absPath);
-    if (entries.length === 0 || entries[0].name !== 'mimetype') {
-      throw new Error('not a KDNA Asset Container: first entry is not mimetype');
-    }
-    if (entries[0].method !== 0) {
-      throw new Error('not a KDNA Asset Container: mimetype must be uncompressed');
-    }
+    // Open once so parsing and the whole-file digest come from the same
+    // immutable snapshot, without a path-level TOCTOU window.
+    containerBytes = fs.readFileSync(absPath);
+    entries = listZipEntriesFromBuffer(containerBytes);
     for (const e of entries) {
       // We only need the well-known entries; signatures/ attachments/ etc.
       // are passed through unchanged by the loader but not parsed here.
@@ -577,25 +579,36 @@ function readV1Layout(absPath) {
         map[e.name] = e.data;
       }
     }
-    for (const f of V1_REQUIRED_DIR_ENTRIES) {
-      if (!map[f]) {
-        throw new Error(`not a KDNA Asset Container: missing ${f}`);
-      }
-    }
   } else {
     throw new Error(`not a file or directory: ${absPath}`);
   }
 
-  // mimetype content must equal the literal v1 media type.
+  const containerDigest = kind === 'file'
+    ? `sha256:${crypto.createHash('sha256').update(containerBytes).digest('hex')}`
+    : null;
+
+  return finalizeV1Layout({ kind, map, entries, containerDigest });
+}
+
+function finalizeV1Layout({ kind, map, entries, containerDigest }) {
+  if (kind !== 'dir' && (!entries || entries.length === 0 || entries[0].name !== 'mimetype')) {
+    throw new Error('not a KDNA Asset Container: first entry is not mimetype');
+  }
+  if (kind !== 'dir' && entries[0].method !== 0) {
+    throw new Error('not a KDNA Asset Container: mimetype must be uncompressed');
+  }
+  for (const required of V1_REQUIRED_DIR_ENTRIES) {
+    if (!map[required]) {
+      const source = kind === 'dir' ? 'KDNA authoring source directory' : 'KDNA Asset Container';
+      throw new Error(`not a ${source}: missing ${required}`);
+    }
+  }
+
   const mime = map.mimetype.toString('utf8');
   if (mime !== MIMETYPE) {
-    throw new Error(
-      `not a KDNA layout: mimetype is "${mime}", expected "${MIMETYPE}"`,
-    );
+    throw new Error(`not a KDNA layout: mimetype is "${mime}", expected "${MIMETYPE}"`);
   }
 
-  // Lineage must be a single object, not an array. (Format rule from
-  // docs/core/manifest.md / schema/manifest.schema.json.)
   let manifest;
   try {
     manifest = parseJsonEntry('kdna.json', map['kdna.json']);
@@ -606,7 +619,60 @@ function readV1Layout(absPath) {
     throw new Error('kdna.json.lineage must be an object, not an array');
   }
 
-  return { kind, map, manifest, entries };
+  return { kind, map, manifest, entries, containerDigest };
+}
+
+function readV1LayoutBytes(input) {
+  const bytes = Buffer.isBuffer(input) ? input : Buffer.from(input);
+  const entries = listZipEntriesFromBuffer(bytes);
+  const map = {};
+  for (const entry of entries) {
+    if (
+      entry.name === 'mimetype' ||
+      entry.name === 'kdna.json' ||
+      entry.name === 'payload.kdnab' ||
+      entry.name === 'checksums.json'
+    ) {
+      map[entry.name] = entry.data;
+    }
+  }
+  return finalizeV1Layout({
+    kind: 'memory',
+    map,
+    entries,
+    containerDigest: `sha256:${crypto.createHash('sha256').update(bytes).digest('hex')}`,
+  });
+}
+
+function readInputLayout(input) {
+  if (Buffer.isBuffer(input) || input instanceof Uint8Array) {
+    return readV1LayoutBytes(input);
+  }
+  return readV1Layout(path.resolve(input));
+}
+
+function snapshotPackagedInput(input) {
+  if (Buffer.isBuffer(input) || input instanceof Uint8Array) {
+    return Buffer.from(input);
+  }
+  if (typeof input !== 'string') return input;
+  const resolved = path.resolve(input);
+  let stat;
+  try {
+    stat = fs.statSync(resolved);
+  } catch {
+    return input;
+  }
+  // Authoring directories remain available to inspect/validate. Runtime
+  // wrappers reject them; this helper only freezes packaged-file loads.
+  return stat.isFile() ? fs.readFileSync(resolved) : input;
+}
+
+function inputSource(input, kind) {
+  return {
+    kind,
+    path: typeof input === 'string' ? path.resolve(input) : null,
+  };
 }
 
 function parseJsonEntry(name, bytes, opts = {}) {
@@ -739,6 +805,21 @@ function runValidate(v1) {
     }
   }
 
+  // Known pre-1.0 aliases are not extension fields. Rejecting them here keeps
+  // the current v1 validator as the single manifest authority while allowing
+  // genuinely namespaced/forward-compatible manifest extensions.
+  const removedAliases = {
+    kdna_spec: 'kdna_version',
+    format_version: 'kdna_version',
+    spec_version: 'kdna_version',
+  };
+  for (const [field, replacement] of Object.entries(removedAliases)) {
+    if (Object.prototype.hasOwnProperty.call(v1.manifest, field)) {
+      result.schema_valid = false;
+      problems.push(`kdna.json: ${field} is not allowed. Use ${replacement}.`);
+    }
+  }
+
   // payload gate — payload.kdnab against payload-profile-v1.schema.json
   // For actually encrypted payloads (envelopes), skip schema validation.
   let payload;
@@ -828,6 +909,43 @@ function runValidate(v1) {
 }
 
 function verifyDigests(checksums, map, problems, result) {
+  const digestMetadataPresent =
+    checksums.digest_profile !== undefined || checksums.covered_entries !== undefined;
+  if (digestMetadataPresent) {
+    const requiredDigestFields = [
+      'digest_profile',
+      'covered_entries',
+      'manifest_digest',
+      'payload_digest',
+      'entry_set_digest',
+    ];
+    const missingDigestFields = requiredDigestFields.filter(
+      (field) => checksums[field] === undefined,
+    );
+    if (missingDigestFields.length) {
+      problems.push(
+        `checksums: kdna-runtime-entry-set-v1 metadata requires ${missingDigestFields.join(', ')}`,
+      );
+      result.checksums_valid = false;
+      return false;
+    }
+    if (checksums.digest_profile !== 'kdna-runtime-entry-set-v1') {
+      problems.push('checksums: unsupported digest_profile (expected kdna-runtime-entry-set-v1)');
+      result.checksums_valid = false;
+      return false;
+    }
+    const coveredEntries = checksums.covered_entries;
+    if (
+      !Array.isArray(coveredEntries)
+      || coveredEntries.length !== 2
+      || coveredEntries[0] !== 'kdna.json'
+      || coveredEntries[1] !== 'payload.kdnab'
+    ) {
+      problems.push('checksums: covered_entries does not match kdna-runtime-entry-set-v1');
+      result.checksums_valid = false;
+      return false;
+    }
+  }
   const algo = checksums.algorithm || 'sha256';
   if (algo !== 'sha256') {
     problems.push(`checksums: unsupported digest algorithm ${algo} (supported: sha256)`);
@@ -857,21 +975,30 @@ function verifyDigests(checksums, map, problems, result) {
       stillValid = false;
     }
   }
-  if (checksums.asset_digest) {
-    const expectedAssetDigest = checksums.asset_digest.replace(/^sha256:/, '');
+  if (
+    checksums.entry_set_digest
+    && checksums.asset_digest
+    && checksums.entry_set_digest !== checksums.asset_digest
+  ) {
+    problems.push('checksums: entry_set_digest does not match deprecated asset_digest alias');
+    stillValid = false;
+  }
+  const declaredEntrySetDigest = checksums.entry_set_digest || checksums.asset_digest;
+  if (declaredEntrySetDigest) {
+    const digestLabel = checksums.entry_set_digest ? 'entry_set_digest' : 'asset_digest';
+    const expectedEntrySetDigest = declaredEntrySetDigest.replace(/^sha256:/, '');
     const missingAssetInputs = ['kdna.json', 'payload.kdnab'].filter((entryName) => !entryDigests[entryName]);
     if (missingAssetInputs.length) {
-      problems.push(`checksums: asset_digest cannot be verified without ${missingAssetInputs.join(', ')}`);
+      problems.push(`checksums: ${digestLabel} cannot be verified without ${missingAssetInputs.join(', ')}`);
       stillValid = false;
     } else {
-      const combined = Object.keys(entryDigests)
-        .sort()
-        .map((name) => `${name}:${entryDigests[name]}`)
-        .join('\n');
-      const actualAssetDigest = crypto.createHash('sha256').update(combined).digest('hex');
-      if (actualAssetDigest !== expectedAssetDigest) {
+      const actualEntrySetDigest = computeRuntimeEntrySetDigest(
+        map['kdna.json'],
+        map['payload.kdnab'],
+      ).slice('sha256:'.length);
+      if (actualEntrySetDigest !== expectedEntrySetDigest) {
         problems.push(
-          `checksums: asset_digest mismatch (declared ${expectedAssetDigest.slice(0, 8)}..., actual ${actualAssetDigest.slice(0, 8)}...)`,
+          `checksums: ${digestLabel} mismatch (declared ${expectedEntrySetDigest.slice(0, 8)}..., actual ${actualEntrySetDigest.slice(0, 8)}...)`,
         );
         stillValid = false;
       }
@@ -904,6 +1031,28 @@ function digestEntry(sourceDir, entry) {
   };
 }
 
+function computeRuntimeEntrySetDigest(manifestBytes, payloadBytes) {
+  if (
+    (!Buffer.isBuffer(manifestBytes) && !(manifestBytes instanceof Uint8Array))
+    || (!Buffer.isBuffer(payloadBytes) && !(payloadBytes instanceof Uint8Array))
+  ) {
+    const error = new Error(
+      'E requires raw uncompressed kdna.json and payload.kdnab bytes.',
+    );
+    error.code = 'KDNA_DIGEST_INPUT_INVALID';
+    throw error;
+  }
+  const entries = {
+    'kdna.json': crypto.createHash('sha256').update(manifestBytes).digest('hex'),
+    'payload.kdnab': crypto.createHash('sha256').update(payloadBytes).digest('hex'),
+  };
+  const combined = Object.keys(entries)
+    .sort()
+    .map((name) => `${name}:${entries[name]}`)
+    .join('\n');
+  return `sha256:${crypto.createHash('sha256').update(combined).digest('hex')}`;
+}
+
 function buildChecksumsV1(sourceDir) {
   const absSrc = path.resolve(sourceDir);
   if (!fs.existsSync(absSrc) || !fs.statSync(absSrc).isDirectory()) {
@@ -914,16 +1063,18 @@ function buildChecksumsV1(sourceDir) {
     'kdna.json': digestEntry(absSrc, 'kdna.json'),
     'payload.kdnab': digestEntry(absSrc, 'payload.kdnab'),
   };
-  const combined = Object.keys(entries)
-    .sort()
-    .map((name) => `${name}:${entries[name].value}`)
-    .join('\n');
-
+  const entrySetDigest = computeRuntimeEntrySetDigest(
+    fs.readFileSync(path.join(absSrc, 'kdna.json')),
+    fs.readFileSync(path.join(absSrc, 'payload.kdnab')),
+  );
   return {
+    digest_profile: 'kdna-runtime-entry-set-v1',
+    covered_entries: ['kdna.json', 'payload.kdnab'],
     algorithm: 'sha256',
     manifest_digest: `sha256:${entries['kdna.json'].value}`,
     payload_digest: `sha256:${entries['payload.kdnab'].value}`,
-    asset_digest: `sha256:${crypto.createHash('sha256').update(combined).digest('hex')}`,
+    entry_set_digest: entrySetDigest,
+    asset_digest: entrySetDigest,
     entries,
   };
 }
@@ -1061,7 +1212,7 @@ function unpack(inputPath, outputDir) {
 // ─── Public router entry points ────────────────────────────────────────
 
 function inspect(inputPath, _opts = {}) {
-  const v1 = readV1Layout(path.resolve(inputPath));
+  const v1 = readInputLayout(inputPath);
   const out = buildInspectOutput(v1);
   // Guard against accidental forbidden wording in any future field additions.
   assertNoForbiddenTerms(out);
@@ -1069,7 +1220,7 @@ function inspect(inputPath, _opts = {}) {
 }
 
 function validate(inputPath, _opts = {}) {
-  const v1 = readV1Layout(path.resolve(inputPath));
+  const v1 = readInputLayout(inputPath);
   return runValidate(v1);
 }
 
@@ -1178,7 +1329,7 @@ function baseLoadPlan(inputPath, v1, validation, opts = {}) {
     issues: [],
     source: {
       kind: v1.kind,
-      path: path.resolve(inputPath),
+      path: typeof inputPath === 'string' ? path.resolve(inputPath) : null,
     },
   };
 
@@ -1218,6 +1369,7 @@ function canonicalToV1Layout(asset) {
     map,
     manifest: asset.manifest,
     entries: Object.keys(map),
+    containerDigest: asset.containerDigest || null,
   };
 }
 
@@ -1229,9 +1381,26 @@ function canonicalToV1Layout(asset) {
 function planLoad(inputPath, opts = {}) {
   let v1;
 
+  if (Buffer.isBuffer(inputPath) || inputPath instanceof Uint8Array) {
+    try {
+      v1 = readInputLayout(inputPath);
+    } catch (e) {
+      return finalizeLoadPlan({
+        kdna_version: null,
+        asset: { asset_id: null, asset_uid: null, title: null, version: null, judgment_version: null },
+        access: null, access_alias: null, entitlement_profile: null,
+        state: 'invalid', required_action: 'block', can_load_now: false, projection_policy: 'none',
+        input_fingerprint: null,
+        checks: { format_valid: false, schema_valid: false, payload_valid: false, checksums_valid: false, load_contract_valid: false, overall_valid: false },
+        issues: [buildLoadPlanIssue('KDNA_FORMAT_INVALID', 'blocking', e.message)],
+        source: inputSource(inputPath, 'memory'),
+      });
+    }
+  }
+
   // Try the unified container dispatcher first; the internal compatibility
   // reader below remains available only for authoring and migration tooling.
-  if (readAsset !== null) {
+  if (!v1 && readAsset !== null) {
     try {
       const asset = readAsset(path.resolve(inputPath));
       v1 = canonicalToV1Layout(asset);
@@ -1251,7 +1420,7 @@ function planLoad(inputPath, opts = {}) {
             e.code === 'KDNA_FORMAT_UNKNOWN' ? 'KDNA_FORMAT_UNKNOWN' : 'KDNA_FORMAT_INVALID',
             'blocking', e.message,
           )],
-          source: { kind: null, path: path.resolve(inputPath) },
+          source: inputSource(inputPath, null),
         });
       }
     }
@@ -1259,7 +1428,7 @@ function planLoad(inputPath, opts = {}) {
 
   if (!v1) {
     try {
-      v1 = readV1Layout(path.resolve(inputPath));
+      v1 = readInputLayout(inputPath);
     } catch (e) {
       return finalizeLoadPlan({
         kdna_version: null,
@@ -1269,7 +1438,7 @@ function planLoad(inputPath, opts = {}) {
         input_fingerprint: null,
         checks: { format_valid: false, schema_valid: false, payload_valid: false, checksums_valid: false, load_contract_valid: false, overall_valid: false },
         issues: [buildLoadPlanIssue('KDNA_FORMAT_INVALID', 'blocking', e.message)],
-        source: { kind: null, path: path.resolve(inputPath) },
+        source: inputSource(inputPath, null),
       });
     }
   }
@@ -1714,6 +1883,7 @@ module.exports = {
   planLoad,
   loadAuthorized,
   buildChecksums: buildChecksumsV1,
+  computeRuntimeEntrySetDigest,
   pack,
   unpack,
   load: loadV1,
@@ -1806,7 +1976,11 @@ function sanitizePrompt(s) {
 }
 
 function loadAuthorized(inputPath, opts = {}) {
-  const plan = planLoad(inputPath, opts);
+  // A packaged path is read exactly once. Authorization and projection must
+  // operate on the same immutable byte snapshot even if the path changes
+  // while this synchronous call is in progress.
+  const inputSnapshot = snapshotPackagedInput(inputPath);
+  const plan = planLoad(inputSnapshot, opts);
   if (plan.can_load_now !== true) {
     const issueCodes = Array.isArray(plan.issues)
       ? plan.issues.map((issue) => issue.code).filter(Boolean)
@@ -1827,7 +2001,7 @@ function loadAuthorized(inputPath, opts = {}) {
       signature_valid: plan.signature_valid === true,
     },
   };
-  return loadV1Unsafe(inputPath, mergedOpts);
+  return loadV1Unsafe(inputSnapshot, mergedOpts);
 }
 
 function loadV1(inputPath, opts = {}) {
@@ -1895,7 +2069,7 @@ function hasCompactPromptContent(content) {
 }
 
 function loadV1Unsafe(inputPath, opts = {}) {
-  const v1 = readV1Layout(path.resolve(inputPath));
+  const v1 = readInputLayout(inputPath);
   const m = v1.manifest;
   const profile = opts.profile || (m.load_contract ? m.load_contract.default_profile : 'compact') || 'compact';
   const as = opts.as || 'json';
@@ -2218,7 +2392,7 @@ function loadV1Unsafe(inputPath, opts = {}) {
     return result;
   }
 
-  return wrapAsCapsule(result, v1, profile, opts);
+  return wrapAsCapsule(result, v1, profile, { ...opts, as });
 }
 
 function wrapAsCapsule(result, v1, profile, opts) {
@@ -2231,14 +2405,10 @@ function wrapAsCapsule(result, v1, profile, opts) {
 function buildCapsule(loadResult, v1, profile, opts = {}) {
   const m = v1.manifest;
   const val = opts._validation || {};
-  const assetDigest = v1.assetDigest || (v1.map && v1.map['checksums.json']
-    ? (() => {
-        try {
-          const checks = JSON.parse(v1.map['checksums.json'].toString('utf8'));
-          return checks.asset_digest || null;
-        } catch { return null; }
-      })()
-    : null);
+  const assetDigest = computeRuntimeEntrySetDigest(
+    v1.map && v1.map['kdna.json'],
+    v1.map && v1.map['payload.kdnab'],
+  );
 
   const pubkey = (m.creator && m.creator.pubkey) || (m.author && m.author.pubkey) || null;
   const sigVerified = val.signature_valid === true;

package/src/v1/index.mjs

@@ -10,6 +10,7 @@ export const validate = v1.validate;
 export const planLoad = v1.planLoad;
 export const loadAuthorized = v1.loadAuthorized;
 export const buildChecksums = v1.buildChecksums;
+export const computeRuntimeEntrySetDigest = v1.computeRuntimeEntrySetDigest;
 export const pack = v1.pack;
 export const unpack = v1.unpack;
 export const load = v1.load;