@aikdna/kdna-core 0.11.1 → 0.12.1

package/src/v1/index.js

@@ -43,6 +43,29 @@ 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'];
 const V1_OPTIONAL_DIR_ENTRIES = ['checksums.json', 'signatures', 'attachments'];
+const V1_ALLOWED_TOP_LEVEL_ENTRIES = new Set([
+  ...V1_REQUIRED_DIR_ENTRIES,
+  ...V1_OPTIONAL_DIR_ENTRIES,
+]);
+const V1_FORBIDDEN_LEGACY_TOP_LEVEL = new Set([
+  'KDNA_Core.json',
+  'KDNA_Patterns.json',
+  'KDNA_Scenarios.json',
+  'KDNA_Cases.json',
+  'KDNA_Reasoning.json',
+  'KDNA_Evolution.json',
+]);
+
+const DEFAULT_CONTAINER_LIMITS = Object.freeze({
+  maxContainerBytes: 25 * 1024 * 1024,
+  maxEntries: 128,
+  maxEntryBytes: 5 * 1024 * 1024,
+  maxTotalUncompressedBytes: 12 * 1024 * 1024,
+  maxCompressionRatio: 100,
+  maxJsonDepth: 64,
+  maxJsonArrayLength: 10000,
+  maxJsonStringLength: 1024 * 1024,
+});
 
 // Words that must never appear in v1 CLI output as positive claims.
 // Schema-valid, signature-valid, compatible — those are fine.
@@ -141,15 +164,15 @@ function detectContainerFormat(absPath) {
   fs.closeSync(fd);
   if (head[0] !== 0x50 || head[1] !== 0x4b) return null;
 
-  // Read the first entry's name + content. We re-use listZipEntries.
-  let entries;
+  // Read only the first central-directory entry. Dangerous later entries
+  // must not make detection fall through to a less strict legacy route;
+  // readV1Layout/validate will reject them with the secure container reader.
+  let first;
   try {
-    entries = listZipEntries(absPath);
+    first = readFirstZipEntry(absPath);
   } catch {
     return null;
   }
-  if (entries.length === 0) return null;
-  const first = entries[0];
   if (first.name !== 'mimetype') return null;
   // The mimetype entry must be STORED (method 0).
   if (first.method !== 0) return null;
@@ -167,8 +190,13 @@ function detectContainerFormat(absPath) {
  * `data` is already decompressed. Throws on unsupported methods or
  * truncated input.
  */
-function listZipEntries(absPath) {
+function listZipEntries(absPath, opts = {}) {
+  const secure = opts.secure !== false;
+  const limits = { ...DEFAULT_CONTAINER_LIMITS, ...(opts.limits || {}) };
   const buf = fs.readFileSync(absPath);
+  if (secure && buf.length > limits.maxContainerBytes) {
+    throw new Error(`container exceeds maximum size (${limits.maxContainerBytes} bytes)`);
+  }
 
   // Locate EOCD — search backwards within the 64KiB comment window.
   let eocdOff = -1;
@@ -183,8 +211,13 @@ function listZipEntries(absPath) {
 
   const totalEntries = buf.readUInt16LE(eocdOff + 10);
   const cdOffset = buf.readUInt32LE(eocdOff + 16);
+  if (secure && totalEntries > limits.maxEntries) {
+    throw new Error(`container has too many entries (${totalEntries} > ${limits.maxEntries})`);
+  }
 
   const entries = [];
+  const seenNames = new Set();
+  let totalUncompressed = 0;
   let p = cdOffset;
   for (let i = 0; i < totalEntries; i++) {
     if (buf.readUInt32LE(p) !== 0x02014b50) {
@@ -196,8 +229,30 @@ function listZipEntries(absPath) {
     const nameLen = buf.readUInt16LE(p + 28);
     const extraLen = buf.readUInt16LE(p + 30);
     const commentLen = buf.readUInt16LE(p + 32);
+    const externalAttributes = buf.readUInt32LE(p + 38);
     const localOff = buf.readUInt32LE(p + 42);
     const name = buf.slice(p + 46, p + 46 + nameLen).toString('utf8');
+    const normalizedName = secure ? normalizeContainerEntryName(name) : name;
+
+    if (secure) {
+      validateContainerEntryMetadata({
+        name,
+        normalizedName,
+        method,
+        compressedSize: compSize,
+        uncompressedSize: uncompSize,
+        externalAttributes,
+        seenNames,
+        limits,
+      });
+      totalUncompressed += uncompSize;
+      if (totalUncompressed > limits.maxTotalUncompressedBytes) {
+        throw new Error(
+          `container uncompressed content exceeds maximum (${limits.maxTotalUncompressedBytes} bytes)`,
+        );
+      }
+      seenNames.add(normalizedName);
+    }
 
     if (buf.readUInt32LE(localOff) !== 0x04034b50) {
       throw new Error(`bad local-file-header for entry ${name}`);
@@ -211,13 +266,17 @@ function listZipEntries(absPath) {
     if (method === 0) data = comp;
     else if (method === 8) data = zlib.inflateRawSync(comp);
     else throw new Error(`unsupported compression method ${method} for ${name}`);
+    if (secure && data.length !== uncompSize) {
+      throw new Error(`entry size mismatch for ${normalizedName}`);
+    }
 
     entries.push({
-      name,
+      name: secure ? normalizedName : name,
       method,
       compressedSize: compSize,
       uncompressedSize: uncompSize,
       localOffset: localOff,
+      externalAttributes,
       data,
     });
     p += 46 + nameLen + extraLen + commentLen;
@@ -225,6 +284,106 @@ function listZipEntries(absPath) {
   return entries;
 }
 
+function readFirstZipEntry(absPath) {
+  const buf = fs.readFileSync(absPath);
+  let eocdOff = -1;
+  const minStart = Math.max(0, buf.length - 65557);
+  for (let i = buf.length - 22; i >= minStart; i--) {
+    if (buf.readUInt32LE(i) === 0x06054b50) {
+      eocdOff = i;
+      break;
+    }
+  }
+  if (eocdOff < 0) throw new Error('not a ZIP/.kdna container (no EOCD)');
+  const totalEntries = buf.readUInt16LE(eocdOff + 10);
+  if (totalEntries === 0) throw new Error('empty ZIP/.kdna container');
+  const cdOffset = buf.readUInt32LE(eocdOff + 16);
+  if (buf.readUInt32LE(cdOffset) !== 0x02014b50) {
+    throw new Error(`bad central-directory entry at offset ${cdOffset}`);
+  }
+  const method = buf.readUInt16LE(cdOffset + 10);
+  const compSize = buf.readUInt32LE(cdOffset + 20);
+  const uncompSize = buf.readUInt32LE(cdOffset + 24);
+  const nameLen = buf.readUInt16LE(cdOffset + 28);
+  const extraLen = buf.readUInt16LE(cdOffset + 30);
+  const localOff = buf.readUInt32LE(cdOffset + 42);
+  const name = buf.slice(cdOffset + 46, cdOffset + 46 + nameLen).toString('utf8');
+  if (buf.readUInt32LE(localOff) !== 0x04034b50) {
+    throw new Error(`bad local-file-header for entry ${name}`);
+  }
+  const lNameLen = buf.readUInt16LE(localOff + 26);
+  const lExtraLen = buf.readUInt16LE(localOff + 28);
+  const compStart = localOff + 30 + lNameLen + lExtraLen;
+  const comp = buf.slice(compStart, compStart + compSize);
+  const data = method === 0 ? comp : method === 8 ? zlib.inflateRawSync(comp) : Buffer.alloc(0);
+  return { name, method, compressedSize: compSize, uncompressedSize: uncompSize, localOffset: localOff, extraLen, data };
+}
+
+function normalizeContainerEntryName(name) {
+  if (typeof name !== 'string' || name.length === 0) {
+    throw new Error('container entry has an empty name');
+  }
+  const normalized = name.normalize('NFC');
+  if (normalized !== name) {
+    throw new Error(`container entry uses a non-canonical Unicode name: ${name}`);
+  }
+  if (normalized.includes('\\')) {
+    throw new Error(`container entry uses backslash path separators: ${name}`);
+  }
+  if (normalized.startsWith('/') || /^[A-Za-z]:\//.test(normalized)) {
+    throw new Error(`container entry uses an absolute path: ${name}`);
+  }
+  const parts = normalized.split('/');
+  if (parts.some((part) => part === '' || part === '.' || part === '..')) {
+    throw new Error(`container entry uses an unsafe relative path: ${name}`);
+  }
+  return normalized;
+}
+
+function validateContainerEntryMetadata(entry) {
+  const {
+    name,
+    normalizedName,
+    method,
+    compressedSize,
+    uncompressedSize,
+    externalAttributes,
+    seenNames,
+    limits,
+  } = entry;
+
+  if (seenNames.has(normalizedName)) {
+    throw new Error(`container has duplicate entry: ${normalizedName}`);
+  }
+  const topLevel = normalizedName.split('/')[0];
+  if (!V1_ALLOWED_TOP_LEVEL_ENTRIES.has(topLevel)) {
+    if (V1_FORBIDDEN_LEGACY_TOP_LEVEL.has(topLevel)) {
+      throw new Error(`container includes forbidden top-level source entry: ${topLevel}`);
+    }
+    throw new Error(`container includes unsupported top-level entry: ${topLevel}`);
+  }
+  if ((topLevel === 'signatures' || topLevel === 'attachments') && normalizedName === topLevel) {
+    throw new Error(`container directory entry is not supported: ${name}`);
+  }
+  if (method !== 0 && method !== 8) {
+    throw new Error(`unsupported compression method ${method} for ${normalizedName}`);
+  }
+  if (uncompressedSize > limits.maxEntryBytes) {
+    throw new Error(`container entry ${normalizedName} exceeds maximum size (${limits.maxEntryBytes} bytes)`);
+  }
+  if (compressedSize > 0 && uncompressedSize / compressedSize > limits.maxCompressionRatio) {
+    throw new Error(`container entry ${normalizedName} exceeds maximum compression ratio`);
+  }
+
+  const mode = externalAttributes >>> 16;
+  const type = mode & 0o170000;
+  const symlink = type === 0o120000;
+  const deviceOrSpecial = type === 0o020000 || type === 0o060000 || type === 0o010000 || type === 0o140000;
+  if (symlink || deviceOrSpecial) {
+    throw new Error(`container entry ${normalizedName} has unsupported file attributes`);
+  }
+}
+
 /**
  * CRC-32 (IEEE 802.3) used by ZIP.
  */
@@ -330,11 +489,11 @@ function readV1Layout(absPath) {
   let stat;
   try {
     stat = fs.statSync(absPath);
-  } catch (e) {
+  } catch {
     throw new Error(`path not found: ${absPath}`);
   }
 
-  let map = {};
+  const map = {};
   let entries = null; // ZIP entries if container
   let kind = null; // 'dir' | 'file'
 
@@ -345,6 +504,9 @@ function readV1Layout(absPath) {
       if (!fs.existsSync(full)) {
         throw new Error(`not a KDNA v1 source dir: missing ${f}`);
       }
+      if (fs.lstatSync(full).isSymbolicLink()) {
+        throw new Error(`not a KDNA v1 source dir: ${f} must not be a symlink`);
+      }
     }
     for (const f of [...V1_REQUIRED_DIR_ENTRIES, ...V1_OPTIONAL_DIR_ENTRIES]) {
       const full = path.join(absPath, f);
@@ -399,7 +561,7 @@ function readV1Layout(absPath) {
   // docs/core/manifest.md / schema/manifest.schema.json.)
   let manifest;
   try {
-    manifest = JSON.parse(map['kdna.json'].toString('utf8'));
+    manifest = parseJsonEntry('kdna.json', map['kdna.json']);
   } catch (e) {
     throw new Error(`kdna.json is not valid JSON: ${e.message}`);
   }
@@ -410,6 +572,43 @@ function readV1Layout(absPath) {
   return { kind, map, manifest, entries };
 }
 
+function parseJsonEntry(name, bytes, opts = {}) {
+  if (!Buffer.isBuffer(bytes)) {
+    throw new Error(`${name} is not a file entry`);
+  }
+  const limits = { ...DEFAULT_CONTAINER_LIMITS, ...(opts.limits || {}) };
+  if (bytes.length > limits.maxEntryBytes) {
+    throw new Error(`${name} exceeds maximum size (${limits.maxEntryBytes} bytes)`);
+  }
+  const parsed = JSON.parse(bytes.toString('utf8'));
+  assertJsonWithinLimits(parsed, name, limits);
+  return parsed;
+}
+
+function assertJsonWithinLimits(value, name, limits) {
+  function walk(node, depth) {
+    if (depth > limits.maxJsonDepth) {
+      throw new Error(`${name} exceeds maximum JSON depth (${limits.maxJsonDepth})`);
+    }
+    if (typeof node === 'string') {
+      if (node.length > limits.maxJsonStringLength) {
+        throw new Error(`${name} contains a string exceeding ${limits.maxJsonStringLength} characters`);
+      }
+      return;
+    }
+    if (node === null || typeof node !== 'object') return;
+    if (Array.isArray(node)) {
+      if (node.length > limits.maxJsonArrayLength) {
+        throw new Error(`${name} contains an array exceeding ${limits.maxJsonArrayLength} items`);
+      }
+      for (const item of node) walk(item, depth + 1);
+      return;
+    }
+    for (const child of Object.values(node)) walk(child, depth + 1);
+  }
+  walk(value, 0);
+}
+
 // ─── inspect ───────────────────────────────────────────────────────────
 
 /**
@@ -485,7 +684,7 @@ function runValidate(v1) {
   // payload gate — payload.kdnab against payload-profile-v1.schema.json
   let payload;
   try {
-    payload = JSON.parse(v1.map['payload.kdnab'].toString('utf8'));
+    payload = parseJsonEntry('payload.kdnab', v1.map['payload.kdnab']);
   } catch (e) {
     result.payload_valid = false;
     problems.push(`payload: not valid JSON (${e.message})`);
@@ -502,7 +701,7 @@ function runValidate(v1) {
   if (v1.map['checksums.json']) {
     let checks;
     try {
-      checks = JSON.parse(v1.map['checksums.json'].toString('utf8'));
+      checks = parseJsonEntry('checksums.json', v1.map['checksums.json']);
     } catch (e) {
       result.checksums_valid = false;
       problems.push(`checksums: not valid JSON (${e.message})`);
@@ -737,7 +936,7 @@ function unpack(inputPath, outputDir) {
 
 // ─── Public router entry points ────────────────────────────────────────
 
-function inspect(inputPath, opts = {}) {
+function inspect(inputPath, _opts = {}) {
   const v1 = readV1Layout(path.resolve(inputPath));
   const out = buildInspectOutput(v1);
   // Guard against accidental forbidden wording in any future field additions.
@@ -745,11 +944,342 @@ function inspect(inputPath, opts = {}) {
   return out;
 }
 
-function validate(inputPath, opts = {}) {
+function validate(inputPath, _opts = {}) {
   const v1 = readV1Layout(path.resolve(inputPath));
   return runValidate(v1);
 }
 
+function normalizeAccess(access) {
+  const value = access || 'public';
+  if (value === 'open') return { access: 'public', alias: value };
+  if (value === 'protected') return { access: 'licensed', alias: value };
+  if (value === 'runtime') return { access: 'remote', alias: value };
+  return { access: value, alias: null };
+}
+
+function inferEntitlementProfile(manifest) {
+  if (manifest.entitlement && typeof manifest.entitlement.profile === 'string') {
+    return manifest.entitlement.profile;
+  }
+  if (manifest.encryption && manifest.encryption.profile === 'kdna-password-protected-v1') {
+    return 'password';
+  }
+  if (manifest.access === 'protected') return 'password';
+  return null;
+}
+
+function buildLoadPlanIssue(code, severity, message) {
+  return { code, severity, message };
+}
+
+function validationProblemCode(problem) {
+  if (/checksums?:/i.test(problem)) return 'KDNA_INTEGRITY_DIGEST_FAILED';
+  if (/signature/i.test(problem)) return 'KDNA_INTEGRITY_SIGNATURE_FAILED';
+  if (/payload:/i.test(problem)) return 'KDNA_FORMAT_INVALID';
+  if (/manifest:/i.test(problem)) return 'KDNA_FORMAT_INVALID';
+  if (/load_contract:/i.test(problem)) return 'KDNA_FORMAT_INVALID';
+  return 'KDNA_FORMAT_INVALID';
+}
+
+function finalizeLoadPlan(plan) {
+  assertNoForbiddenTerms(plan);
+  return plan;
+}
+
+function baseLoadPlan(inputPath, v1, validation) {
+  const manifest = v1.manifest;
+  const accessInfo = normalizeAccess(manifest.access);
+  const entitlementProfile = inferEntitlementProfile(manifest);
+  const asset = {
+    asset_id: manifest.asset_id || null,
+    asset_uid: manifest.asset_uid || null,
+    title: manifest.title || null,
+    version: manifest.version || null,
+    judgment_version: manifest.judgment_version || null,
+  };
+
+  const plan = {
+    kdna_version: manifest.kdna_version || null,
+    asset,
+    access: accessInfo.access,
+    access_alias: accessInfo.alias,
+    entitlement_profile: entitlementProfile,
+    state: 'invalid',
+    required_action: 'block',
+    can_load_now: false,
+    projection_policy: 'none',
+    checks: {
+      format_valid: validation.format_valid,
+      schema_valid: validation.schema_valid,
+      payload_valid: validation.payload_valid,
+      checksums_valid: validation.checksums_valid,
+      load_contract_valid: validation.load_contract_valid,
+      overall_valid: validation.overall_valid,
+    },
+    issues: [],
+    source: {
+      kind: v1.kind,
+      path: path.resolve(inputPath),
+    },
+  };
+
+  if (accessInfo.alias) {
+    plan.issues.push(buildLoadPlanIssue(
+      'KDNA_AUTH_ACCESS_ALIAS',
+      'info',
+      `Access value "${accessInfo.alias}" is treated as "${accessInfo.access}".`,
+    ));
+  }
+
+  return plan;
+}
+
+/**
+ * Plan a KDNA v1 runtime load without decrypting or emitting judgment content.
+ * Product consumers such as Chat should render authorization UI from this
+ * result instead of parsing manifest fields directly.
+ */
+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',
+      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);
+  const plan = baseLoadPlan(inputPath, v1, validation);
+
+  if (!validation.overall_valid) {
+    plan.state = 'invalid';
+    plan.required_action = 'block';
+    plan.can_load_now = false;
+    plan.projection_policy = 'none';
+    for (const problem of validation.problems) {
+      plan.issues.push(buildLoadPlanIssue(validationProblemCode(problem), 'blocking', problem));
+    }
+    return finalizeLoadPlan(plan);
+  }
+
+  const manifest = v1.manifest;
+  const payloadDeclaredEncrypted =
+    manifest.payload && manifest.payload.encrypted === true;
+  const encryptedEntries = Array.isArray(manifest.encryption && manifest.encryption.encrypted_entries)
+    ? manifest.encryption.encrypted_entries
+    : [];
+  const hasEncryptedPayload = payloadDeclaredEncrypted || encryptedEntries.length > 0;
+
+  if (!['public', 'licensed', 'remote'].includes(plan.access)) {
+    const unknownAccess = plan.access;
+    plan.access = null;
+    plan.state = 'invalid';
+    plan.required_action = 'block';
+    plan.issues.push(buildLoadPlanIssue(
+      'KDNA_ACCESS_MODE_UNKNOWN',
+      'blocking',
+      `Unknown access value "${unknownAccess}".`,
+    ));
+    return finalizeLoadPlan(plan);
+  }
+
+  if (plan.access === 'remote') {
+    plan.state = 'needs_runtime';
+    plan.required_action = 'connect_runtime';
+    plan.can_load_now = false;
+    plan.projection_policy = 'remote';
+    plan.issues.push(buildLoadPlanIssue(
+      'KDNA_AUTH_REMOTE_RUNTIME_REQUIRED',
+      'blocking',
+      'Remote assets require a runtime projection endpoint.',
+    ));
+    return finalizeLoadPlan(plan);
+  }
+
+  if (plan.access === 'licensed') {
+    const knownProfiles = new Set([
+      'password',
+      'local_receipt',
+      'account',
+      'org',
+      'purchase_receipt',
+      'device_bound',
+    ]);
+    if (plan.entitlement_profile && !knownProfiles.has(plan.entitlement_profile)) {
+      plan.state = 'invalid';
+      plan.required_action = 'block';
+      plan.can_load_now = false;
+      plan.projection_policy = 'none';
+      plan.issues.push(buildLoadPlanIssue(
+        'KDNA_ENTITLEMENT_PROFILE_UNKNOWN',
+        'blocking',
+        `Unknown entitlement profile "${plan.entitlement_profile}".`,
+      ));
+      return finalizeLoadPlan(plan);
+    }
+
+    if (plan.entitlement_profile === 'password') {
+      if (opts.password || opts.hasPassword === true) {
+        if (opts.hasPassword === true && !opts.password) {
+          plan.issues.push(buildLoadPlanIssue(
+            'KDNA_AUTH_PASSWORD_DIAGNOSTIC',
+            'info',
+            'hasPassword is a diagnostic credential-presence signal only; it does not verify the password.',
+          ));
+        }
+        plan.state = 'ready';
+        plan.required_action = 'load';
+        plan.can_load_now = true;
+        plan.projection_policy = 'minimal';
+      } else {
+        plan.state = 'needs_password';
+        plan.required_action = 'enter_password';
+        plan.can_load_now = false;
+        plan.projection_policy = 'none';
+        plan.issues.push(buildLoadPlanIssue(
+          'KDNA_AUTH_PASSWORD_REQUIRED',
+          'blocking',
+          'A password is required before this asset can be loaded.',
+        ));
+      }
+      return finalizeLoadPlan(plan);
+    }
+
+    if (plan.entitlement_profile === 'account') {
+      plan.state = 'needs_account';
+      plan.required_action = 'sign_in_or_activate';
+      plan.can_load_now = false;
+      plan.projection_policy = 'none';
+      plan.issues.push(buildLoadPlanIssue(
+        'KDNA_AUTH_ACCOUNT_REQUIRED',
+        'blocking',
+        'Account authorization is required before this asset can be loaded.',
+      ));
+      return finalizeLoadPlan(plan);
+    }
+
+    if (plan.entitlement_profile === 'org') {
+      plan.state = 'needs_org_auth';
+      plan.required_action = 'sign_in_or_activate';
+      plan.can_load_now = false;
+      plan.projection_policy = 'none';
+      plan.issues.push(buildLoadPlanIssue(
+        'KDNA_AUTH_ORG_REQUIRED',
+        'blocking',
+        'Organization authorization is required before this asset can be loaded.',
+      ));
+      return finalizeLoadPlan(plan);
+    }
+
+    if (opts.entitlement && opts.entitlement.status === 'active') {
+      plan.state = 'ready';
+      plan.required_action = 'load';
+      plan.can_load_now = true;
+      plan.projection_policy = 'minimal';
+      return finalizeLoadPlan(plan);
+    }
+
+    if (opts.entitlement && opts.entitlement.status === 'expired') {
+      plan.state = 'expired';
+      plan.required_action = 'sync';
+      plan.can_load_now = false;
+      plan.projection_policy = 'none';
+      plan.issues.push(buildLoadPlanIssue(
+        'KDNA_AUTH_EXPIRED',
+        'blocking',
+        'The entitlement is expired.',
+      ));
+      return finalizeLoadPlan(plan);
+    }
+
+    if (opts.entitlement && opts.entitlement.status === 'revoked') {
+      plan.state = 'revoked';
+      plan.required_action = 'block';
+      plan.can_load_now = false;
+      plan.projection_policy = 'none';
+      plan.issues.push(buildLoadPlanIssue(
+        'KDNA_AUTH_REVOKED',
+        'blocking',
+        'The entitlement has been revoked.',
+      ));
+      return finalizeLoadPlan(plan);
+    }
+
+    if (opts.entitlement && opts.entitlement.status === 'offline_grace') {
+      plan.state = 'offline_grace';
+      plan.required_action = 'sync';
+      plan.can_load_now = true;
+      plan.projection_policy = 'minimal';
+      plan.issues.push(buildLoadPlanIssue(
+        'KDNA_AUTH_OFFLINE_GRACE_ACTIVE',
+        'warning',
+        'The entitlement can load during offline grace but must sync before grace expires.',
+      ));
+      return finalizeLoadPlan(plan);
+    }
+
+    plan.state = 'needs_license';
+    plan.required_action = plan.entitlement_profile === 'local_receipt' ? 'install_receipt' : 'sign_in_or_activate';
+    plan.can_load_now = false;
+    plan.projection_policy = 'none';
+    plan.issues.push(buildLoadPlanIssue(
+      'KDNA_AUTH_ENTITLEMENT_REQUIRED',
+      'blocking',
+      'A valid entitlement is required before this asset can be loaded.',
+    ));
+    return finalizeLoadPlan(plan);
+  }
+
+  if (hasEncryptedPayload) {
+    plan.state = 'invalid';
+    plan.required_action = 'block';
+    plan.can_load_now = false;
+    plan.projection_policy = 'none';
+    plan.issues.push(buildLoadPlanIssue(
+      'KDNA_CRYPTO_PROFILE_UNSUPPORTED',
+      'blocking',
+      'Encrypted entries require licensed access.',
+    ));
+    return finalizeLoadPlan(plan);
+  }
+
+  plan.state = 'ready';
+  plan.required_action = 'load';
+  plan.can_load_now = true;
+  plan.projection_policy = 'minimal';
+  return finalizeLoadPlan(plan);
+}
+
 function assertNoForbiddenTerms(obj) {
   const seen = new Set();
   function walk(o) {
@@ -781,6 +1311,8 @@ module.exports = {
   readV1Layout,
   inspect,
   validate,
+  planLoad,
+  loadAuthorized,
   buildChecksumsV1,
   pack,
   unpack,
@@ -797,6 +1329,9 @@ function renderPromptItem(item) {
 
   if (item.type === 'axiom_applicability' && item.one_sentence) {
     const parts = [item.one_sentence];
+    if (Array.isArray(item.applies_when) && item.applies_when.length) {
+      parts.push(`applies when: ${item.applies_when.slice(0, 2).join('; ')}`);
+    }
     if (Array.isArray(item.does_not_apply_when) && item.does_not_apply_when.length) {
       parts.push(`does not apply when: ${item.does_not_apply_when.slice(0, 2).join('; ')}`);
     }
@@ -819,7 +1354,52 @@ function renderPromptItem(item) {
   return JSON.stringify(item);
 }
 
+function loadAuthorized(inputPath, opts = {}) {
+  const plan = planLoad(inputPath, opts);
+  if (plan.can_load_now !== true) {
+    const issueCodes = Array.isArray(plan.issues)
+      ? plan.issues.map((issue) => issue.code).filter(Boolean)
+      : [];
+    const err = new Error(
+      `LoadPlan denied loading: state=${plan.state || 'invalid'} required_action=${plan.required_action || 'block'}`,
+    );
+    err.code = issueCodes[0] || 'KDNA_LOAD_NOT_AUTHORIZED';
+    err.plan = plan;
+    throw err;
+  }
+  return loadV1Unsafe(inputPath, opts);
+}
+
 function loadV1(inputPath, opts = {}) {
+  return loadAuthorized(inputPath, opts);
+}
+
+function normalizeCompactAxiom(axiom) {
+  if (typeof axiom === 'string') {
+    return {
+      type: 'axiom_applicability',
+      statement: axiom,
+      one_sentence: axiom,
+      applies_when: [],
+      does_not_apply_when: [],
+      failure_risk: null,
+    };
+  }
+  if (!axiom || typeof axiom !== 'object') return null;
+  const statement = axiom.statement || axiom.one_sentence || axiom.full_statement || axiom.id || null;
+  if (!statement) return null;
+  return {
+    type: 'axiom_applicability',
+    id: axiom.id || null,
+    statement,
+    one_sentence: axiom.one_sentence || statement,
+    applies_when: Array.isArray(axiom.applies_when) ? axiom.applies_when : [],
+    does_not_apply_when: Array.isArray(axiom.does_not_apply_when) ? axiom.does_not_apply_when : [],
+    failure_risk: axiom.failure_risk || null,
+  };
+}
+
+function loadV1Unsafe(inputPath, opts = {}) {
   const v1 = readV1Layout(path.resolve(inputPath));
   const m = v1.manifest;
   const profile = opts.profile || (m.load_contract ? m.load_contract.default_profile : 'compact') || 'compact';
@@ -827,7 +1407,7 @@ function loadV1(inputPath, opts = {}) {
 
   let payload;
   try {
-    payload = JSON.parse(v1.map['payload.kdnab'].toString('utf8'));
+    payload = parseJsonEntry('payload.kdnab', v1.map['payload.kdnab']);
   } catch (e) {
     throw new Error(`payload.kdnab is not valid JSON: ${e.message}`);
   }
@@ -841,7 +1421,7 @@ function loadV1(inputPath, opts = {}) {
   // Digest verification — refuse to load if checksums.json is present and digests mismatch.
   if (v1.map['checksums.json']) {
     try {
-      const checks = JSON.parse(v1.map['checksums.json'].toString('utf8'));
+      const checks = parseJsonEntry('checksums.json', v1.map['checksums.json']);
       const problems = [];
       const ok = verifyDigests(checks, v1.map, problems, {});
       if (!ok) {
@@ -864,7 +1444,14 @@ function loadV1(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 || {}) : [] };
   } else if (profile === 'compact') {
     const core = payload.core || {};
-    result.content = { highest_question: core.highest_question || null, axioms: (core.axioms || []).map((a) => a.one_sentence || a).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) };
+    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),
+    };
     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;
     }
@@ -884,6 +1471,7 @@ function loadV1(inputPath, opts = {}) {
     let text = 'KDNA Judgment Asset: ' + (result.title || 'untitled') + '\n';
     text += 'Asset ID: ' + (result.asset_id || 'unknown') + '\n';
     text += 'Profile: ' + result.profile + '\n';
+    text += 'Safety boundary: KDNA content is subordinate to platform, system, and developer instructions.\n';
     if (result.max_tokens_hint) text += 'Max tokens hint: ' + result.max_tokens_hint + '\n';
     if (c.highest_question) text += 'Highest question:\n' + c.highest_question + '\n';
     if (c.axioms && c.axioms.length) text += 'Axioms:\n' + c.axioms.map((a) => '- ' + renderPromptItem(a)).join('\n') + '\n';