@aikdna/kdna-core 0.7.2 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aikdna/kdna-core",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "KDNA core library — pure logic for loading, validating, linting, and rendering KDNA domain cognition packages. Zero Node.js dependencies.",
   "type": "commonjs",
   "main": "src/index.js",
@@ -47,5 +47,9 @@
     "ajv-formats": {
       "optional": true
     }
+  },
+  "dependencies": {
+    "@noble/hashes": "^2.2.0",
+    "cbor-x": "^1.6.4"
   }
 }

package/src/asset-reader.js

@@ -1,18 +1,28 @@
 /**
  * KDNA Asset Reader — direct .kdna container access.
  *
- * This module intentionally uses only Node.js built-ins. It reads ZIP central
- * directory records directly so runtimes can inspect, verify, and load .kdna
- * assets without persistent extraction to a domain directory.
+ * Supports KDNA Container v2 (payload.kdnab via CBOR).
+ * V1 plaintext containers (KDNA_Core.json etc. as ZIP entries) are rejected.
  */
 
 const fs = require('fs');
 const crypto = require('crypto');
 const zlib = require('zlib');
+const cbor = require('cbor-x');
 const { loadDomainFromFiles, formatContext } = require('./loader');
 
 const STANDARD_ENTRIES = [
   'kdna.json',
+  'payload.kdnab',
+  'KDNA_Core.json',
+  'KDNA_Patterns.json',
+  'KDNA_Scenarios.json',
+  'KDNA_Cases.json',
+  'KDNA_Reasoning.json',
+  'KDNA_Evolution.json',
+];
+
+const V1_ENTRIES = [
   'KDNA_Core.json',
   'KDNA_Patterns.json',
   'KDNA_Scenarios.json',
@@ -274,6 +284,53 @@ function verifyMediaType(asset, errors) {
   }
 }
 
+/**
+ * Verify Human Lock signatures on locked axiom cards.
+ * Reconstructs signing payload (cardId|statement|fingerprint) and verifies
+ * against the creator's public key from kdna.json manifest.author.
+ */
+function verifyHumanLockSignatures(coreData, manifest, errors, warnings) {
+  const publicKeyPEM = manifest?.author?.public_key_pem;
+  if (!publicKeyPEM) {
+    // Skip if no public key available (unsigned assets are valid)
+    return;
+  }
+  const axioms = coreData?.axioms || [];
+  if (!Array.isArray(axioms) || axioms.length === 0) return;
+
+  let verified = 0, missing = 0, invalid = 0;
+  for (const ax of axioms) {
+    const hl = ax.human_lock;
+    if (!hl || !hl.signature) {
+      // Only warn for locked cards without signature
+      if (ax.status === 'locked' || ax.status === 'tested' || ax.status === 'published') {
+        missing++;
+      }
+      continue;
+    }
+    try {
+      const payload = [ax.id, hl.statement || '', hl.judgment_fingerprint || ''].join('\n');
+      const sig = Buffer.from(String(hl.signature).replace(/^ed25519:/, ''), 'hex');
+      const key = crypto.createPublicKey(publicKeyPEM);
+      const ok = crypto.verify(null, Buffer.from(payload), key, sig);
+      if (ok) { verified++; }
+      else { invalid++; }
+    } catch {
+      invalid++;
+    }
+  }
+
+  if (invalid > 0) {
+    errors.push(`${invalid} Human Lock signature(s) failed verification — judgment may have been altered`);
+  }
+  if (missing > 0) {
+    warnings.push(`${missing} locked card(s) have no Human Lock signature`);
+  }
+  if (verified > 0 && invalid === 0) {
+    // All signed locks verified — good
+  }
+}
+
 function validateManifestIdentity(manifest, errors, _warnings) {
   if (manifest.kdna_spec) {
     errors.push('kdna.json: kdna_spec is not allowed. Use spec_version.');
@@ -326,6 +383,22 @@ function readManifest(asset) {
 function readDataMapSync(asset, entries = STANDARD_ENTRIES, options = {}) {
   const dataMap = {};
   const manifest = readManifest(asset);
+
+  // ── KDNA Container v2: decode CBOR payload ──
+  if (asset.entries.has('payload.kdnab')) {
+    const payloadBuf = asset.readEntry('payload.kdnab');
+    const payload = cbor.decode(payloadBuf);
+    if (payload && payload.judgment) {
+      if (payload.judgment.core) dataMap['KDNA_Core.json'] = payload.judgment.core;
+      if (payload.judgment.patterns) dataMap['KDNA_Patterns.json'] = payload.judgment.patterns;
+      if (payload.judgment.scenarios) dataMap['KDNA_Scenarios.json'] = payload.judgment.scenarios;
+      if (payload.judgment.cases) dataMap['KDNA_Cases.json'] = payload.judgment.cases;
+      if (payload.judgment.reasoning) dataMap['KDNA_Reasoning.json'] = payload.judgment.reasoning;
+      if (payload.judgment.evolution) dataMap['KDNA_Evolution.json'] = payload.judgment.evolution;
+    }
+    return dataMap;
+  }
+
   const encrypted = encryptedEntries(manifest).filter((entryName) => entries.includes(entryName));
   if (encrypted.length && typeof options.decryptEntry !== 'function') {
     throw new Error(`encrypted entries require decryptEntry hook: ${encrypted.join(', ')}`);
@@ -395,6 +468,15 @@ function verifySync(asset, options = {}) {
       if (options.requireSignature || manifest.signature) {
         signature_valid = verifySignature(asset, manifest, errors, warnings);
       }
+      // ── Human Lock signature verification ──────────────────
+      if (asset.entries.has('KDNA_Core.json')) {
+        try {
+          const coreData = parseJson(asset.readEntry('KDNA_Core.json'), 'KDNA_Core.json');
+          verifyHumanLockSignatures(coreData, manifest, errors, warnings);
+        } catch (e) {
+          warnings.push(`Human Lock signature check skipped: ${e.message}`);
+        }
+      }
     } catch (e) {
       errors.push(e.message);
     }

package/src/crypto-profile.js

@@ -1,5 +1,12 @@
 const crypto = require('crypto');
 
+let argon2id;
+try {
+  ({ argon2id } = require('@noble/hashes/argon2.js'));
+} catch {
+  // Optional: password-protected assets require @noble/hashes
+}
+
 // ── Profile constants ──────────────────────────────────────────────
 
 /**
@@ -18,9 +25,19 @@ const LICENSED_ENTRY_PROFILE = 'kdna-licensed-entry-v1';
  */
 const LICENSED_EXPERIMENTAL_PROFILE = 'kdna-licensed-entry-experimental';
 
+/**
+ * RFC-0009 compliant profile.
+ * - Argon2id password-based key derivation
+ * - AES-256-KW content encryption key wrapping
+ * - AES-256-GCM content encryption
+ * - Dual key slots: password + recovery
+ */
+const PASSWORD_PROTECTED_PROFILE = 'kdna-password-protected-v1';
+
 const RFC_KDF = 'HKDF-SHA256';
 const RFC_KEY_WRAPPING = 'AES-256-KW';
 const LEGACY_KDF = 'scrypt-sha256';
+const PASSWORD_KDF = 'Argon2id';
 const ALG = 'AES-256-GCM';
 
 // ── Helpers ───────────────────────────────────────────────────────
@@ -246,6 +263,163 @@ function decryptLicensedEntryV1(envelopeValue, options = {}) {
   ]);
 }
 
+// ── RFC-0009: Password-protected encryption ───────────────────────
+
+function ensureArgon2id() {
+  if (!argon2id) {
+    throw new Error(
+      'password-protected assets require @noble/hashes. Install: npm install @noble/hashes',
+    );
+  }
+}
+
+function derivePasswordKey(password, params = {}) {
+  ensureArgon2id();
+  const {
+    salt,
+    memory_kib = 65536,
+    iterations = 3,
+    parallelism = 4,
+  } = params;
+  if (!salt) throw new Error('salt is required for Argon2id');
+  const saltBuf = decodeBase64(salt, 'salt');
+  const passwordBuf = toBuffer(password, 'password');
+  const key = argon2id(passwordBuf, saltBuf, {
+    t: iterations,
+    m: memory_kib,
+    p: parallelism,
+    dkLen: 32,
+  });
+  return Buffer.from(key);
+}
+
+function generateRecoveryCode() {
+  const raw = crypto.randomBytes(32); // 256 bits
+  const hex = raw.toString('hex').toUpperCase();
+  const groups = hex.match(/.{4}/g);
+  return `kdna-recover-${groups.join('-')}`;
+}
+
+function decodeRecoveryCode(code) {
+  if (typeof code !== 'string' || !code.startsWith('kdna-recover-')) {
+    throw new Error('recovery code must start with "kdna-recover-"');
+  }
+  const hex = code.slice('kdna-recover-'.length).replace(/-/g, '');
+  if (!/^[0-9A-Fa-f]{64}$/.test(hex)) {
+    throw new Error('recovery code format is invalid');
+  }
+  return Buffer.from(hex, 'hex');
+}
+
+function encryptProtectedEntry(plaintext, options = {}) {
+  const { entryName, manifest = {}, password, includeRecovery = true, recoveryCode } = options;
+  if (!entryName) throw new Error('entryName is required');
+  if (!password) throw new Error('password is required for protected encryption');
+
+  const cek = generateCEK();
+
+  // Password slot
+  const salt = crypto.randomBytes(16);
+  const passwordKdf = {
+    name: PASSWORD_KDF,
+    salt: salt.toString('base64'),
+    memory_kib: 65536,
+    iterations: 3,
+    parallelism: 4,
+  };
+  const passwordKey = derivePasswordKey(password, passwordKdf);
+  const passwordWrappedKey = wrapCEK(cek, passwordKey);
+
+  const keySlots = [
+    {
+      slot: 'password',
+      wrap: RFC_KEY_WRAPPING,
+      wrapped_key: passwordWrappedKey.toString('base64'),
+    },
+  ];
+
+  // Recovery slot
+  if (includeRecovery) {
+    const recoveryKey = recoveryCode ? decodeRecoveryCode(recoveryCode) : crypto.randomBytes(32);
+    const recoveryWrappedKey = wrapCEK(cek, recoveryKey);
+    keySlots.push({
+      slot: 'recovery',
+      wrap: RFC_KEY_WRAPPING,
+      wrapped_key: recoveryWrappedKey.toString('base64'),
+    });
+  }
+
+  const iv = crypto.randomBytes(12);
+  const cipher = crypto.createCipheriv('aes-256-gcm', cek, iv);
+  cipher.setAAD(encryptedEntryAad(entryName, manifest, PASSWORD_PROTECTED_PROFILE));
+  const ciphertext = Buffer.concat([cipher.update(toBuffer(plaintext, 'plaintext')), cipher.final()]);
+
+  return {
+    profile: PASSWORD_PROTECTED_PROFILE,
+    alg: ALG,
+    kdf: PASSWORD_KDF,
+    key_wrapping: RFC_KEY_WRAPPING,
+    password_kdf: passwordKdf,
+    key_slots: keySlots,
+    iv: iv.toString('base64'),
+    tag: cipher.getAuthTag().toString('base64'),
+    ciphertext: ciphertext.toString('base64'),
+  };
+}
+
+function decryptProtectedEntry(envelopeValue, options = {}) {
+  const { entryName, manifest = {}, password, recoveryCode } = options;
+  if (!entryName) throw new Error('entryName is required');
+  if (!password && !recoveryCode) {
+    throw new Error('password or recoveryCode is required for protected decryption');
+  }
+
+  const envelope = normalizeEnvelope(envelopeValue);
+  if (envelope.profile !== PASSWORD_PROTECTED_PROFILE) {
+    throw new Error(
+      `unsupported encrypted entry profile: ${envelope.profile || 'unknown'} (expected ${PASSWORD_PROTECTED_PROFILE})`,
+    );
+  }
+  if (envelope.alg !== ALG) throw new Error(`unsupported encrypted entry alg: ${envelope.alg}`);
+  if (envelope.kdf !== PASSWORD_KDF) throw new Error(`unsupported encrypted entry kdf: ${envelope.kdf}`);
+  if (envelope.key_wrapping !== RFC_KEY_WRAPPING) {
+    throw new Error(`unsupported encrypted entry key_wrapping: ${envelope.key_wrapping}`);
+  }
+
+  let cek;
+  if (password) {
+    const passwordKey = derivePasswordKey(password, envelope.password_kdf);
+    const passwordSlot = envelope.key_slots.find((s) => s.slot === 'password');
+    if (!passwordSlot) throw new Error('password slot missing from envelope');
+    cek = unwrapCEK(decodeBase64(passwordSlot.wrapped_key, 'wrapped_key'), passwordKey);
+  } else {
+    const recoveryKey = decodeRecoveryCode(recoveryCode);
+    const recoverySlot = envelope.key_slots.find((s) => s.slot === 'recovery');
+    if (!recoverySlot) throw new Error('recovery slot missing from envelope');
+    cek = unwrapCEK(decodeBase64(recoverySlot.wrapped_key, 'wrapped_key'), recoveryKey);
+  }
+
+  const decipher = crypto.createDecipheriv('aes-256-gcm', cek, decodeBase64(envelope.iv, 'iv'));
+  decipher.setAAD(encryptedEntryAad(entryName, manifest, PASSWORD_PROTECTED_PROFILE));
+  decipher.setAuthTag(decodeBase64(envelope.tag, 'tag'));
+  return Buffer.concat([
+    decipher.update(decodeBase64(envelope.ciphertext, 'ciphertext')),
+    decipher.final(),
+  ]);
+}
+
+function createPasswordDecryptEntry(options = {}) {
+  const { password } = options;
+  return ({ entryName, ciphertext, manifest }) =>
+    decryptProtectedEntry(ciphertext, { entryName, manifest, password });
+}
+
+function createRecoveryDecryptEntry(options = {}) {
+  const { recoveryCode } = options;
+  return ({ entryName, ciphertext, manifest }) =>
+    decryptProtectedEntry(ciphertext, { entryName, manifest, recoveryCode });
+}
+
 // ── Legacy / experimental profile (pre-RFC, backward compat) ───────
 
 function deriveLicensedEntryKeyLegacy(options = {}) {
@@ -329,10 +503,12 @@ module.exports = {
   // Profiles
   LICENSED_ENTRY_PROFILE,
   LICENSED_EXPERIMENTAL_PROFILE,
+  PASSWORD_PROTECTED_PROFILE,
   ALG,
   RFC_KDF,
   RFC_KEY_WRAPPING,
   LEGACY_KDF,
+  PASSWORD_KDF,
 
   // RFC-0008 compliant
   deriveWrappingKey,
@@ -342,6 +518,15 @@ module.exports = {
   encryptLicensedEntryV1,
   decryptLicensedEntryV1,
 
+  // RFC-0009 compliant
+  derivePasswordKey,
+  generateRecoveryCode,
+  decodeRecoveryCode,
+  encryptProtectedEntry,
+  decryptProtectedEntry,
+  createPasswordDecryptEntry,
+  createRecoveryDecryptEntry,
+
   // Legacy
   deriveLicensedEntryKey: deriveLicensedEntryKeyLegacy,
   encryptLicensedEntryLegacy,

package/src/index.js

@@ -9,6 +9,7 @@ const compose = require('./compose');
 const assetReader = require('./asset-reader');
 const cryptoProfile = require('./crypto-profile');
 const publicApi = require('./public-api');
+const workpackPure = require('./workpack-pure');
 
 module.exports = {
   ...publicApi,
@@ -19,4 +20,5 @@ module.exports = {
   ...compose,
   ...assetReader,
   ...cryptoProfile,
+  ...workpackPure,
 };

package/src/workpack-pure.js

@@ -0,0 +1,254 @@
+/**
+ * @aikdna/kdna-core — Work Pack validation (pure logic)
+ *
+ * Zero-dependency pure functions for validating KDNA Work Pack
+ * manifests against the Work Pack schema. Does not depend on ajv
+ * at source level — the validator is injected.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ── Embedded Work Pack Schema v0.1 ──────────────────────────────────
+// Self-contained schema with resolved $refs for zero-dependency validation.
+
+const WORK_PACK_SCHEMA = {
+  $schema: 'http://json-schema.org/draft-07/schema#',
+  $id: 'https://aikdna.com/schemas/work-pack.schema.json',
+  title: 'KDNA Work Pack Manifest',
+  type: 'object',
+  required: ['format', 'format_version', 'name', 'version', 'description', 'status', 'kdna'],
+  properties: {
+    format: { type: 'string', const: 'kdna-workpack' },
+    format_version: { type: 'string', pattern: '^\\d+\\.\\d+$' },
+    name: { type: 'string', pattern: '^[a-z0-9]+(-[a-z0-9]+)*$', maxLength: 64 },
+    version: { type: 'string', pattern: '^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9.]+)?(\\+[a-zA-Z0-9.]+)?$' },
+    description: { type: 'string', maxLength: 280 },
+    status: { type: 'string', enum: ['draft', 'experimental', 'stable', 'deprecated'] },
+    access: { type: 'string', enum: ['open', 'licensed', 'runtime', 'enterprise', 'partner'], default: 'open' },
+    license: { type: 'string', default: 'Apache-2.0' },
+    kdna: {
+      type: 'object',
+      oneOf: [
+        {
+          required: ['mode', 'asset'],
+          properties: {
+            mode: { const: 'single' },
+            asset: {
+              type: 'object',
+              required: ['name', 'version', 'role'],
+              properties: {
+                name: { type: 'string', pattern: '^[a-z0-9_]+$' },
+                version: { type: 'string' },
+                digest: { type: 'string', pattern: '^sha256:[a-f0-9]{64}$' },
+                role: { type: 'string', enum: ['primary', 'constraint', 'fallback'] },
+              },
+              additionalProperties: false,
+            },
+          },
+        },
+        {
+          required: ['mode', 'assets'],
+          properties: {
+            mode: { const: 'cluster' },
+            assets: {
+              type: 'array',
+              minItems: 2,
+              items: {
+                type: 'object',
+                required: ['name', 'version', 'role'],
+                properties: {
+                  name: { type: 'string', pattern: '^[a-z0-9_]+$' },
+                  version: { type: 'string' },
+                  digest: { type: 'string', pattern: '^sha256:[a-f0-9]{64}$' },
+                  role: { type: 'string', enum: ['primary', 'constraint', 'fallback'] },
+                },
+                additionalProperties: false,
+              },
+            },
+          },
+        },
+      ],
+    },
+    skills: {
+      type: 'array',
+      default: [],
+      items: {
+        type: 'object',
+        required: ['name'],
+        properties: {
+          name: { type: 'string', pattern: '^[a-z0-9]+([_-][a-z0-9]+)*$', maxLength: 64 },
+          type: { type: 'string' },
+          required: { type: 'boolean', default: true },
+          mcp_server: { type: ['string', 'null'], default: null },
+          fallback: { type: ['string', 'null'], default: null },
+        },
+        additionalProperties: false,
+      },
+    },
+    templates: {
+      type: 'object',
+      default: {},
+      properties: {
+        task: { type: 'string' },
+        output: { type: 'string' },
+      },
+    },
+    review_gates: {
+      type: 'array',
+      default: [],
+      items: { type: 'string' },
+    },
+    risk_policy: { type: 'string' },
+    trace_policy: { type: 'string' },
+    evals: { type: 'string' },
+  },
+  additionalProperties: false,
+};
+
+// ── Public API ─────────────────────────────────────────────────────
+
+/**
+ * Validate a Work Pack manifest against the schema.
+ *
+ * @param {object} manifest — parsed workpack.json content
+ * @param {object} [opts]
+ * @param {object} [opts.ajv] — optional pre-configured Ajv instance
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+function validateWorkPackManifest(manifest, opts = {}) {
+  const Ajv = opts.ajv || _lazyAjv();
+  let validate;
+  try {
+    validate = Ajv.compile(WORK_PACK_SCHEMA);
+  } catch (e) {
+    return { valid: false, errors: [`Schema compilation error: ${e.message}`] };
+  }
+  const ok = validate(manifest);
+  if (ok) return { valid: true, errors: [] };
+  const errors = (validate.errors || []).map(
+    (e) => `${e.instancePath || '/'}: ${e.message}`
+  );
+  return { valid: false, errors };
+}
+
+/**
+ * Check structural completeness — verify all referenced files exist.
+ *
+ * @param {object} manifest — parsed workpack.json
+ * @param {string} rootDir — directory containing workpack.json
+ * @returns {{ complete: boolean, missing: string[] }}
+ */
+function checkWorkPackStructure(manifest, rootDir) {
+  const missing = [];
+  const refs = [];
+
+  if (manifest.templates) {
+    if (manifest.templates.task) refs.push(manifest.templates.task);
+    if (manifest.templates.output) refs.push(manifest.templates.output);
+  }
+  if (manifest.review_gates) refs.push(...manifest.review_gates);
+  if (manifest.risk_policy) refs.push(manifest.risk_policy);
+  if (manifest.trace_policy) refs.push(manifest.trace_policy);
+  if (manifest.evals) refs.push(manifest.evals);
+
+  for (const ref of refs) {
+    const fullPath = path.resolve(rootDir, ref);
+    if (!fs.existsSync(fullPath)) missing.push(ref);
+  }
+
+  return { complete: missing.length === 0, missing };
+}
+
+/**
+ * Inspect a Work Pack — return a structured summary.
+ *
+ * @param {object} manifest — parsed workpack.json
+ * @param {string} rootDir — directory containing workpack.json
+ * @returns {object}
+ */
+function inspectWorkPack(manifest, rootDir) {
+  const kdnaMode = manifest.kdna?.mode || 'unknown';
+  const kdnaCount =
+    kdnaMode === 'single' ? 1 : (manifest.kdna?.assets || []).length;
+
+  const structure = checkWorkPackStructure(manifest, rootDir);
+
+  return {
+    name: manifest.name,
+    version: manifest.version,
+    description: manifest.description,
+    status: manifest.status,
+    access: manifest.access || 'open',
+    license: manifest.license || 'Apache-2.0',
+    format_version: manifest.format_version,
+    kdna: {
+      mode: kdnaMode,
+      assets: kdnaMode === 'single'
+        ? [{ name: manifest.kdna.asset.name, version: manifest.kdna.asset.version, role: manifest.kdna.asset.role }]
+        : (manifest.kdna?.assets || []).map(a => ({ name: a.name, version: a.version, role: a.role })),
+    },
+    skills: (manifest.skills || []).map(s => ({
+      name: s.name,
+      type: s.type || 'unspecified',
+      required: s.required !== false,
+      fallback: s.fallback || null,
+    })),
+    templates: manifest.templates
+      ? { task: manifest.templates.task || null, output: manifest.templates.output || null }
+      : null,
+    review_gates: (manifest.review_gates || []).length,
+    has_risk_policy: !!manifest.risk_policy,
+    has_trace_policy: !!manifest.trace_policy,
+    has_evals: !!manifest.evals,
+    structural_complete: structure.complete,
+    missing_files: structure.missing,
+  };
+}
+
+/**
+ * Load a Work Pack from a directory.
+ *
+ * @param {string} dirPath — path to Work Pack directory
+ * @returns {{ manifest: object|null, error: string|null }}
+ */
+function loadWorkPack(dirPath) {
+  const wpPath = path.join(dirPath, 'workpack.json');
+  if (!fs.existsSync(wpPath)) {
+    return { manifest: null, error: `workpack.json not found in ${dirPath}` };
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(wpPath, 'utf8'));
+  } catch (e) {
+    return { manifest: null, error: `Invalid JSON in workpack.json: ${e.message}` };
+  }
+  return { manifest, error: null };
+}
+
+// ── Internal ────────────────────────────────────────────────────────
+
+let _ajvInstance = null;
+
+function _lazyAjv() {
+  if (_ajvInstance) return _ajvInstance;
+  try {
+    const Ajv = require('ajv');
+    const addFormats = require('ajv-formats');
+    _ajvInstance = new Ajv({ allErrors: true, strict: false });
+    addFormats(_ajvInstance);
+    return _ajvInstance;
+  } catch (e) {
+    throw new Error(
+      'ajv is required for Work Pack validation. Install: npm install ajv ajv-formats'
+    );
+  }
+}
+
+module.exports = {
+  WORK_PACK_SCHEMA,
+  validateWorkPackManifest,
+  checkWorkPackStructure,
+  inspectWorkPack,
+  loadWorkPack,
+};