@aikdna/kdna-core 0.13.3 → 0.14.0

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "@aikdna/kdna-core",
-  "version": "0.13.3",
+  "version": "0.14.0",
   "description": "KDNA Core library for validating, planning, and loading local .kdna judgment assets.",
+  "engines": {
+    "node": ">=18.0.0"
+  },
   "type": "commonjs",
   "main": "src/index.js",
   "module": "src/index.mjs",
@@ -63,4 +66,4 @@
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1"
   }
-}
+}

package/src/container-dispatcher.js

@@ -0,0 +1,298 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const { createKdnaAssetReader } = require('../asset-reader.js');
+
+const MIMETYPE_V1 = 'application/vnd.kdna.asset';
+const MIMETYPE_V2 = 'application/vnd.aikdna.kdna+zip';
+
+/**
+ * CanonicalAssetModel — the single internal representation of any KDNA asset,
+ * regardless of whether it came from a source directory, Container v1,
+ * or Canonical Distribution Container (Container v2 / SPEC 2.0).
+ *
+ * All downstream code (planLoad, loadAuthorized, decrypt, loadV1Unsafe)
+ * operates on this model. No consumer should check container format directly.
+ *
+ * @typedef {object} CanonicalAssetModel
+ * @property {'dir'|'file'} sourceKind       — original input type
+ * @property {string}       sourcePath       — resolved absolute path
+ * @property {string}       format           — 'v1-dir' | 'v1-container' | 'v2-container'
+ * @property {string}       mimetype         — normalized mimetype
+ * @property {object}       manifest         — parsed kdna.json
+ * @property {Buffer}       payloadRaw       — raw payload.kdnab bytes (CBOR/JSON)
+ * @property {object|null}  checksums        — parsed checksums.json, or null
+ * @property {Buffer|null}  assetDigest      — SHA-256 of entire container (file only)
+ * @property {Buffer|null}  containerBuffer  — full container bytes (for ZIP inputs, may be null for dirs)
+ * @property {Map<string, Buffer>|null} entries — raw entry map (for v1 dir layout; null for v2/container)
+ */
+
+/**
+ * Read any KDNA asset into a CanonicalAssetModel.
+ *
+ * Handles:
+ *   - Source directories (mimetype + kdna.json + payload.kdnab on disk)
+ *   - Container v1 (.kdna ZIP with application/vnd.kdna.asset mimetype)
+ *   - Canonical containers (.kdna ZIP with application/vnd.aikdna.kdna+zip mimetype)
+ *
+ * @param {string} inputPath - absolute path to asset file or directory
+ * @param {object} [opts]
+ * @param {object} [opts.limits] - container size/entry limits
+ * @returns {CanonicalAssetModel}
+ */
+function readAsset(inputPath, opts = {}) {
+  const absPath = path.resolve(inputPath);
+  const stat = fs.statSync(absPath);
+
+  if (stat.isDirectory()) {
+    return readSourceDirectory(absPath, opts);
+  }
+
+  if (!stat.isFile()) {
+    throw Object.assign(
+      new Error(`Not a file or directory: ${absPath}`),
+      { code: 'KDNA_PATH_NOT_FOUND' },
+    );
+  }
+
+  const format = detectFormat(absPath);
+  if (format === 'v1-container') {
+    return readV1Container(absPath, opts);
+  }
+  if (format === 'v2-container') {
+    return readV2Container(absPath, opts);
+  }
+
+  throw Object.assign(
+    new Error(`Unknown KDNA container format: ${absPath}`),
+    { code: 'KDNA_FORMAT_UNKNOWN' },
+  );
+}
+
+/**
+ * Detect the container format of a .kdna file.
+ * Returns 'v1-container', 'v2-container', or throws.
+ */
+function detectFormat(absPath) {
+  const buf = fs.readFileSync(absPath);
+  if (buf.length < 4) {
+    throw Object.assign(
+      new Error(`File too small to be a KDNA container: ${absPath}`),
+      { code: 'KDNA_FORMAT_INVALID' },
+    );
+  }
+
+  // Must be a ZIP (PK signature)
+  const sig = buf.readUInt32LE(0);
+  if (sig !== 0x04034b50) {
+    throw Object.assign(
+      new Error(`Not a valid ZIP/KDNA container: ${absPath}`),
+      { code: 'KDNA_FORMAT_INVALID' },
+    );
+  }
+
+  // Read the mimetype from the first entry (central directory first entry)
+  const eocdOffset = findEocd(buf);
+  let cdOffset = buf.readUInt32LE(eocdOffset + 16);
+  const cdEntryCount = buf.readUInt16LE(eocdOffset + 10);
+
+  for (let i = 0; i < cdEntryCount; i++) {
+    const entryOffset = cdOffset;
+    const nameLen = buf.readUInt16LE(entryOffset + 28);
+    const extraLen = buf.readUInt16LE(entryOffset + 30);
+    const commentLen = buf.readUInt16LE(entryOffset + 32);
+    const name = buf.toString('utf8', entryOffset + 46, entryOffset + 46 + nameLen);
+
+    if (name !== 'mimetype') {
+      cdOffset = entryOffset + 46 + nameLen + extraLen + commentLen;
+      continue;
+    }
+
+    const method = buf.readUInt16LE(entryOffset + 10);
+    if (method !== 0) {
+      throw Object.assign(
+        new Error('mimetype entry must be stored (no compression)'),
+        { code: 'KDNA_FORMAT_INVALID' },
+      );
+    }
+
+    const localOffset = buf.readUInt32LE(entryOffset + 42);
+    const localNameLen = buf.readUInt16LE(localOffset + 26);
+    const localExtraLen = buf.readUInt16LE(localOffset + 28);
+    const dataOffset = localOffset + 30 + localNameLen + localExtraLen;
+    const compressedSize = buf.readUInt32LE(entryOffset + 20);
+    const mime = buf.toString('utf8', dataOffset, dataOffset + compressedSize).trim();
+
+    if (mime === MIMETYPE_V1) return 'v1-container';
+    if (mime === MIMETYPE_V2) return 'v2-container';
+
+    throw Object.assign(
+      new Error(`Unknown KDNA mimetype: ${mime}`),
+      { code: 'KDNA_FORMAT_UNKNOWN' },
+    );
+  }
+
+  throw Object.assign(
+    new Error('No mimetype entry found in KDNA container'),
+    { code: 'KDNA_FORMAT_INVALID' },
+  );
+}
+
+function findEocd(buf) {
+  const maxSearch = Math.min(buf.length, 65557);
+  for (let i = buf.length - 22; i >= buf.length - maxSearch && i >= 0; i--) {
+    if (buf.readUInt32LE(i) === 0x06054b50) {
+      return i;
+    }
+  }
+  throw Object.assign(
+    new Error('EOCD record not found in ZIP container'),
+    { code: 'KDNA_FORMAT_INVALID' },
+  );
+}
+
+/**
+ * Read a source directory into CanonicalAssetModel.
+ */
+function readSourceDirectory(absPath, _opts) {
+  const mimetypePath = path.join(absPath, 'mimetype');
+  const manifestPath = path.join(absPath, 'kdna.json');
+  const payloadPath = path.join(absPath, 'payload.kdnab');
+  const checksumsPath = path.join(absPath, 'checksums.json');
+
+  if (!fs.existsSync(mimetypePath) || !fs.existsSync(manifestPath) || !fs.existsSync(payloadPath)) {
+    throw Object.assign(
+      new Error(`Source directory missing required entries: ${absPath}`),
+      { code: 'KDNA_FORMAT_INVALID' },
+    );
+  }
+
+  const mimetype = fs.readFileSync(mimetypePath, 'utf8').trim();
+  if (![MIMETYPE_V1, MIMETYPE_V2].includes(mimetype)) {
+    throw Object.assign(
+      new Error(`Unknown mimetype in source directory: ${mimetype}`),
+      { code: 'KDNA_FORMAT_UNKNOWN' },
+    );
+  }
+
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch (e) {
+    throw Object.assign(
+      new Error(`Invalid kdna.json in source directory: ${e.message}`),
+      { code: 'KDNA_MANIFEST_PARSE_ERROR' },
+    );
+  }
+
+  const payloadRaw = fs.readFileSync(payloadPath);
+  const checksums = fs.existsSync(checksumsPath)
+    ? JSON.parse(fs.readFileSync(checksumsPath, 'utf8'))
+    : null;
+
+  const entries = new Map();
+  for (const entryName of fs.readdirSync(absPath)) {
+    const entryPath = path.join(absPath, entryName);
+    if (fs.statSync(entryPath).isFile()) {
+      entries.set(entryName, fs.readFileSync(entryPath));
+    }
+  }
+
+  return {
+    sourceKind: 'dir',
+    sourcePath: absPath,
+    format: 'v1-dir',
+    mimetype,
+    manifest,
+    payloadRaw,
+    checksums,
+    assetDigest: null,
+    containerBuffer: null,
+    entries,
+  };
+}
+
+/**
+ * Read a Container v1 (.kdna with v1 mimetype) into CanonicalAssetModel.
+ */
+function readV1Container(absPath, _opts) {
+  // Delegate to the existing v1 layout reader for validation
+  const v1Layout = require('../v1/index.js').readV1Layout(absPath);
+
+  const containerBuf = fs.readFileSync(absPath);
+  const assetDigest = crypto.createHash('sha256').update(containerBuf).digest();
+
+  return {
+    sourceKind: 'file',
+    sourcePath: absPath,
+    format: 'v1-container',
+    mimetype: MIMETYPE_V1,
+    manifest: v1Layout.manifest,
+    payloadRaw: v1Layout.map['payload.kdnab'] || null,
+    checksums: v1Layout.map['checksums.json']
+      ? (() => { try { return JSON.parse(v1Layout.map['checksums.json'].toString('utf8')); } catch { return null; } })()
+      : null,
+    assetDigest,
+    containerBuffer: containerBuf,
+    entries: new Map(Object.entries(v1Layout.map)),
+  };
+}
+
+/**
+ * Read a Canonical Container (v2 mimetype) into CanonicalAssetModel.
+ * Uses the existing KdnaAssetReader for ZIP parsing.
+ */
+function readV2Container(absPath, _opts) {
+  const reader = createKdnaAssetReader();
+  const asset = reader.openSync(absPath);
+
+  const manifest = reader.readManifestSync(asset);
+  const payloadRaw = reader.readEntrySync(asset, 'payload.kdnab');
+  const checksums = (() => {
+    try {
+      const raw = reader.readEntrySync(asset, 'checksums.json');
+      return raw ? JSON.parse(raw.toString('utf8')) : null;
+    } catch {
+      return null;
+    }
+  })();
+
+  return {
+    sourceKind: 'file',
+    sourcePath: absPath,
+    format: 'v2-container',
+    mimetype: MIMETYPE_V2,
+    manifest,
+    payloadRaw,
+    checksums,
+    assetDigest: Buffer.from(asset.asset_digest.replace(/^sha256:/, ''), 'hex'),
+    containerBuffer: fs.readFileSync(absPath),
+    entries: null, // v2 uses lazy reads, not pre-loaded map
+  };
+}
+
+/**
+ * Extract the mimetype from a CanonicalAssetModel.
+ */
+function getMimetype(asset) {
+  return asset.mimetype;
+}
+
+/**
+ * Determine if a CanonicalAssetModel represents a source directory.
+ */
+function isSourceDirectory(asset) {
+  return asset.sourceKind === 'dir';
+}
+
+module.exports = {
+  MIMETYPE_V1,
+  MIMETYPE_V2,
+  readAsset,
+  detectFormat,
+  getMimetype,
+  isSourceDirectory,
+};

package/src/v1/index.js

@@ -39,6 +39,14 @@ const path = require('node:path');
 const zlib = require('node:zlib');
 const crypto = require('node:crypto');
 
+const { readAsset } = (() => {
+  try {
+    return require('../container-dispatcher.js');
+  } catch {
+    return { readAsset: null, MIMETYPE_V1: null, MIMETYPE_V2: null };
+  }
+})();
+
 const MIMETYPE_V1 = 'application/vnd.kdna.asset';
 const MIMETYPE_V2 = 'application/vnd.aikdna.kdna+zip';
 const V1_REQUIRED_DIR_ENTRIES = ['mimetype', 'kdna.json', 'payload.kdnab'];
@@ -682,6 +690,7 @@ function runValidate(v1) {
   }
 
   // payload gate — payload.kdnab against payload-profile-v1.schema.json
+  // For actually encrypted payloads (envelopes), skip schema validation.
   let payload;
   try {
     payload = parseJsonEntry('payload.kdnab', v1.map['payload.kdnab']);
@@ -690,7 +699,26 @@ function runValidate(v1) {
     problems.push(`payload: not valid JSON (${e.message})`);
     return finalizeValidate(result, problems);
   }
-  if (!validators.payload(payload)) {
+
+  const isEncryptedPayload = payload.profile
+    && payload.ciphertext
+    && (v1.manifest.payload?.encrypted || v1.manifest.encryption?.encrypted_entries?.includes('payload.kdnab'));
+
+  if (isEncryptedPayload) {
+    // Encrypted payload — verify it's a proper encryption envelope, not plaintext.
+    const encProfile = v1.manifest.encryption?.profile;
+    if (encProfile && payload.profile !== encProfile) {
+      result.payload_valid = false;
+      problems.push(`payload: encrypted envelope profile ${payload.profile || 'unknown'} does not match manifest encryption profile ${encProfile}`);
+    }
+    const hasKeyMaterial = !!payload.wrapped_key || (Array.isArray(payload.key_slots) && payload.key_slots.length > 0);
+    if (!payload.profile || !payload.ciphertext || !hasKeyMaterial) {
+      result.payload_valid = false;
+      problems.push('payload: encrypted envelope missing required fields (profile/ciphertext/key material)');
+    }
+    // Encrypted payload passes payload gate if envelope is structurally valid.
+  } else if (!validators.payload(payload)) {
+    // Plaintext payload — full schema validation.
     result.payload_valid = false;
     for (const err of validators.payload.errors) {
       problems.push(`payload: ${err.instancePath || '<root>'} ${err.message}`);
@@ -1089,6 +1117,23 @@ function baseLoadPlan(inputPath, v1, validation, opts = {}) {
   return plan;
 }
 
+// ─── B1: Unified container model → legacy v1 layout ─────────────────────
+
+function canonicalToV1Layout(asset) {
+  const map = {};
+  if (asset.entries) {
+    for (const [name, buf] of asset.entries) {
+      map[name] = buf;
+    }
+  }
+  return {
+    kind: asset.sourceKind,
+    map,
+    manifest: asset.manifest,
+    entries: Object.keys(map),
+  };
+}
+
 /**
  * Plan a KDNA v1 runtime load without decrypting or emitting judgment content.
  * Product consumers such as Chat should render authorization UI from this
@@ -1096,42 +1141,49 @@ function baseLoadPlan(inputPath, v1, validation, opts = {}) {
  */
 function planLoad(inputPath, opts = {}) {
   let v1;
-  try {
-    v1 = readV1Layout(path.resolve(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: {
-        kind: null,
-        path: path.resolve(inputPath),
-      },
-    });
+
+  // Try the unified container dispatcher first (handles v1 dirs, v1 containers, v2 containers)
+  if (readAsset !== null) {
+    try {
+      const asset = readAsset(path.resolve(inputPath));
+      v1 = canonicalToV1Layout(asset);
+    } catch (e) {
+      // If dispatcher fails, fall back to legacy readV1Layout for backward compat
+      if (e.code === 'KDNA_FORMAT_UNKNOWN' || e.code === 'KDNA_PATH_NOT_FOUND') {
+        // let the legacy path handle it
+      } else {
+        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(
+            e.code === 'KDNA_FORMAT_UNKNOWN' ? 'KDNA_FORMAT_UNKNOWN' : 'KDNA_FORMAT_INVALID',
+            'blocking', e.message,
+          )],
+          source: { kind: null, path: path.resolve(inputPath) },
+        });
+      }
+    }
+  }
+
+  if (!v1) {
+    try {
+      v1 = readV1Layout(path.resolve(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: { kind: null, path: path.resolve(inputPath) },
+      });
+    }
   }
 
   const validation = runValidate(v1);
@@ -1530,15 +1582,53 @@ function loadV1Unsafe(inputPath, opts = {}) {
 
   let payload;
   try {
-    payload = parseJsonEntry('payload.kdnab', v1.map['payload.kdnab']);
+    const rawPayload = v1.map['payload.kdnab'];
+    payload = parseJsonEntry('payload.kdnab', rawPayload);
   } catch (e) {
     throw new Error(`payload.kdnab is not valid JSON: ${e.message}`);
   }
 
-  if (payload.encrypted === true || (v1.map.mimetype && v1.map.mimetype.includes('encrypted'))) {
-    const err = new Error('payload is encrypted and cannot be decrypted without a key');
-    err.code = 'requires_decryption';
-    throw err;
+  if (payload.profile && payload.ciphertext && (m.payload?.encrypted || m.encryption?.encrypted_entries?.includes('payload.kdnab'))) {
+    // B4: Attempt decryption when password or decrypt hook is available.
+    if (opts.decryptEntry) {
+      // Consumer-provided decrypt hook (e.g., licensed entry key)
+      try {
+        const decrypted = opts.decryptEntry({
+          asset: { entries: v1.map, manifest: m },
+          manifest: m,
+          entryName: 'payload.kdnab',
+          ciphertext: v1.map['payload.kdnab'],
+        });
+        const decryptedBuf = typeof decrypted === 'string'
+          ? Buffer.from(decrypted, 'utf8')
+          : Buffer.from(decrypted);
+        payload = parseJsonEntry('payload.kdnab', decryptedBuf);
+      } catch (e) {
+        const err = new Error(`Decryption failed: ${e.message}`);
+        err.code = 'KDNA_DECRYPT_FAILED';
+        throw err;
+      }
+    } else if (opts.password) {
+      // Password-based decryption via kdna-password-protected-v1 profile
+      try {
+        const { decryptProtectedEntry } = require('../crypto-profile.js');
+        const encryptedEnvelope = v1.map['payload.kdnab'].toString('utf8');
+        const decryptedBuf = decryptProtectedEntry(encryptedEnvelope, {
+          entryName: 'payload.kdnab',
+          manifest: m,
+          password: opts.password,
+        });
+        payload = parseJsonEntry('payload.kdnab', decryptedBuf);
+      } catch (e) {
+        const err = new Error(`Decryption failed with provided password: ${e.message}`);
+        err.code = 'KDNA_DECRYPT_FAILED';
+        throw err;
+      }
+    } else {
+      const err = new Error('payload is encrypted and cannot be decrypted without a password or license key');
+      err.code = 'KDNA_AUTH_PASSWORD_REQUIRED';
+      throw err;
+    }
   }
 
   // Digest verification — refuse to load if checksums.json is present and digests mismatch.
@@ -1593,23 +1683,24 @@ function loadV1Unsafe(inputPath, opts = {}) {
     result.content = { asset_id: m.asset_id, asset_uid: m.asset_uid, title: m.title, version: m.version, judgment_version: m.judgment_version, asset_type: m.asset_type, summary: m.summary || null, language: m.language || null, keywords: m.keywords || [], profiles_available: m.load_contract ? Object.keys(m.load_contract.profiles || {}) : [], max_tokens_hint: maxTokensHint };
   } else if (profile === 'compact') {
     const core = payload.core || {};
+    const normalizeList = (items) => (items || []).map((item) => {
+      if (typeof item === 'string') return { type: 'text', text: item };
+      if (item && typeof item === 'object') return item;
+      return null;
+    }).filter(Boolean);
     result.content = {
       highest_question: core.highest_question || null,
       axioms: (core.axioms || []).map(normalizeCompactAxiom).filter(Boolean),
-      boundaries: core.boundaries || [],
-      self_checks: (payload.reasoning && payload.reasoning.self_checks) || [],
-      failure_modes: (payload.reasoning && payload.reasoning.failure_modes) || [],
-      patterns: (payload.patterns || []).slice(0, 3),
+      boundaries: normalizeList(core.boundaries),
+      self_checks: normalizeList(payload.reasoning && payload.reasoning.self_checks),
+      failure_modes: normalizeList(payload.reasoning && payload.reasoning.failure_modes),
+      patterns: normalizeList(payload.patterns).slice(0, 3),
     };
     if (m.load_contract && m.load_contract.profiles && m.load_contract.profiles.compact && m.load_contract.profiles.compact.max_tokens_hint) {
       result.max_tokens_hint = m.load_contract.profiles.compact.max_tokens_hint;
     }
   } else if (profile === 'scenario') {
-    if (payload.scenarios && payload.scenarios.length > 0) {
-      result.content = { scenarios: payload.scenarios };
-    } else {
-      result.content = null;
-    }
+    result.content = { scenarios: payload.scenarios || [] };
   } else if (profile === 'full') {
     result.content = { manifest: m, payload };
   } else {
@@ -1618,13 +1709,13 @@ function loadV1Unsafe(inputPath, opts = {}) {
 
   if (as === 'prompt') {
     const c = result.content;
-    if (c === null) {
+    if (!c || (c.scenarios && c.scenarios.length === 0 && !c.highest_question && !(c.axioms && c.axioms.length) && !(c.boundaries && c.boundaries.length))) {
       return {
         status: result.status,
         profile: result.profile,
-        profile_available: false,
+        profile_available: result.profile_available,
         available_profiles: result.available_profiles,
-        text: `KDNA Judgment Asset: ${result.title || 'untitled'}\nAsset ID: ${result.asset_id || 'unknown'}\nProfile: ${result.profile}\n\nProfile "${result.profile}" is not available for this asset. Available profiles: ${result.available_profiles.join(', ')}`,
+        text: `KDNA Judgment Asset: ${result.title || 'untitled'}\nAsset ID: ${result.asset_id || 'unknown'}\nProfile: ${result.profile}\n\nNo content available for this profile. Available profiles: ${result.available_profiles.join(', ')}`,
       };
     }
     let text = 'KDNA Judgment Asset: ' + (result.title || 'untitled') + '\n';