@aikdna/kdna-core 0.5.0 → 0.7.0

package/src/crypto-profile.js

@@ -1,9 +1,30 @@
 const crypto = require('crypto');
 
+// ── Profile constants ──────────────────────────────────────────────
+
+/**
+ * RFC-0008 compliant profile.
+ * - HKDF-SHA256 key derivation
+ * - AES-256-KW (RFC 3394) content encryption key wrapping
+ * - AES-256-GCM content encryption
+ * - Random CEK per asset; license key only unwraps CEK, never touches content
+ */
 const LICENSED_ENTRY_PROFILE = 'kdna-licensed-entry-v1';
-const KDF = 'scrypt-sha256';
+
+/**
+ * Pre-RFC legacy profile (now experimental).
+ * Uses scrypt-sha256 with concatenated secret (`licenseKey|machineFingerprint`).
+ * Retained for backward compatibility only.
+ */
+const LICENSED_EXPERIMENTAL_PROFILE = 'kdna-licensed-entry-experimental';
+
+const RFC_KDF = 'HKDF-SHA256';
+const RFC_KEY_WRAPPING = 'AES-256-KW';
+const LEGACY_KDF = 'scrypt-sha256';
 const ALG = 'AES-256-GCM';
 
+// ── Helpers ───────────────────────────────────────────────────────
+
 function toBuffer(value, label) {
   if (Buffer.isBuffer(value)) return value;
   if (value instanceof Uint8Array) return Buffer.from(value);
@@ -25,21 +46,10 @@ function normalizeEnvelope(value) {
   throw new Error('encrypted entry envelope must be JSON');
 }
 
-function deriveLicensedEntryKey(options = {}) {
-  const { licenseKey, machineFingerprint, salt, keyLength = 32 } = options;
-  if (!licenseKey) throw new Error('licenseKey is required');
-  if (!machineFingerprint) throw new Error('machineFingerprint is required');
-  const saltBuffer = Buffer.isBuffer(salt) || salt instanceof Uint8Array
-    ? Buffer.from(salt)
-    : decodeBase64(salt, 'salt');
-  const secret = `${licenseKey}|${machineFingerprint}`;
-  return crypto.scryptSync(secret, saltBuffer, keyLength);
-}
-
-function encryptedEntryAad(entryName, manifest = {}) {
+function encryptedEntryAad(entryName, manifest = {}, profile = LICENSED_ENTRY_PROFILE) {
   return Buffer.from(
     [
-      LICENSED_ENTRY_PROFILE,
+      profile,
       manifest.name || manifest.asset_id || '',
       manifest.version || '',
       entryName,
@@ -48,19 +58,220 @@ function encryptedEntryAad(entryName, manifest = {}) {
   );
 }
 
-function encryptLicensedEntry(plaintext, options = {}) {
+// ── HKDF-SHA256 (RFC 5869) ────────────────────────────────────────
+
+/**
+ * HKDF-SHA256 extract-then-expand.
+ * @param {Buffer|string} ikm — input keying material (license key)
+ * @param {Buffer} [salt] — optional salt (defaults to 32 zero bytes)
+ * @param {Buffer|string} [info] — context info
+ * @param {number} [length] — output length (default 32)
+ */
+function hkdfSha256(ikm, salt = null, info = '', length = 32) {
+  const ikmBuf = toBuffer(ikm, 'ikm');
+  // Extract
+  const saltBuf = salt || Buffer.alloc(32, 0);
+  const prk = crypto.createHmac('sha256', saltBuf).update(ikmBuf).digest();
+  // Expand (single-block expansion for length ≤ 32)
+  const t = crypto.createHmac('sha256', prk)
+    .update(Buffer.concat([
+      toBuffer(info, 'info'),
+      // Counter byte 0x01
+      Buffer.from([1]),
+    ]))
+    .digest();
+  return t.subarray(0, length);
+}
+
+// ── AES-256-KW (RFC 3394) ─────────────────────────────────────────
+
+const AES_BLOCK = 16;
+const KW_IV = Buffer.from('a6a6a6a6a6a6a6a6', 'hex'); // RFC 3394 default IV
+
+function aesWrap(key, plaintext) {
+  // key = 32 bytes, plaintext = 32 bytes (single CEK)
+  if (key.length !== 32) throw new Error('AES-256-KW requires 32-byte key');
+  if (plaintext.length !== 32) throw new Error('AES-256-KW requires 32-byte plaintext');
+
+  const n = plaintext.length / 8; // = 4 for 256-bit CEK
+  const r = new Array(n + 1);
+  r[0] = KW_IV;
+  for (let i = 0; i < n; i++) r[i + 1] = plaintext.subarray(i * 8, (i + 1) * 8);
+
+  for (let j = 0; j <= 5; j++) {
+    for (let i = 1; i <= n; i++) {
+      const input = Buffer.concat([r[0], r[i]]); // 16 bytes
+      const cipher = crypto.createCipheriv('aes-256-ecb', key, null);
+      cipher.setAutoPadding(false);
+      const b = Buffer.concat([cipher.update(input), cipher.final()]);
+      r[0] = b.subarray(0, 8);
+      // XOR t = (n * j) + i as big-endian 64-bit
+      const t = BigInt(n) * BigInt(j) + BigInt(i);
+      const tBuf = Buffer.alloc(8);
+      tBuf.writeBigUInt64BE(t);
+      for (let k = 0; k < 8; k++) r[0][k] ^= tBuf[k];
+      r[i] = b.subarray(8, 16);
+    }
+  }
+
+  const result = Buffer.alloc((n + 1) * 8);
+  for (let i = 0; i <= n; i++) r[i].copy(result, i * 8);
+  return result; // 40 bytes
+}
+
+function aesUnwrap(key, ciphertext) {
+  if (key.length !== 32) throw new Error('AES-256-KW requires 32-byte key');
+  if (ciphertext.length !== 40) throw new Error('AES-256-KW ciphertext must be 40 bytes');
+
+  const n = (ciphertext.length / 8) - 1; // = 4
+  const r = new Array(n + 1);
+  for (let i = 0; i <= n; i++) r[i] = ciphertext.subarray(i * 8, (i + 1) * 8);
+
+  for (let j = 5; j >= 0; j--) {
+    for (let i = n; i >= 1; i--) {
+      const t = BigInt(n) * BigInt(j) + BigInt(i);
+      const tBuf = Buffer.alloc(8);
+      tBuf.writeBigUInt64BE(t);
+      for (let k = 0; k < 8; k++) r[0][k] ^= tBuf[k];
+
+      const input = Buffer.concat([r[0], r[i]]);
+      const decipher = crypto.createDecipheriv('aes-256-ecb', key, null);
+      decipher.setAutoPadding(false);
+      const b = Buffer.concat([decipher.update(input), decipher.final()]);
+      r[0] = b.subarray(0, 8);
+      r[i] = b.subarray(8, 16);
+    }
+  }
+
+  if (!r[0].equals(KW_IV)) throw new Error('AES-256-KW unwrap: integrity check failed');
+  const result = Buffer.alloc(n * 8);
+  for (let i = 1; i <= n; i++) r[i].copy(result, (i - 1) * 8);
+  return result; // 32 bytes
+}
+
+// ── RFC-0008 compliant encryption ─────────────────────────────────
+
+/**
+ * Derive a key-wrapping key (KWK) from a license key via HKDF-SHA256.
+ */
+function deriveWrappingKey(licenseKey, info = 'kdna-licensed-entry-v1-kwk') {
+  return hkdfSha256(licenseKey, null, info, 32);
+}
+
+/**
+ * Generate a random content encryption key (CEK).
+ */
+function generateCEK() {
+  return crypto.randomBytes(32);
+}
+
+/**
+ * Wrap a CEK with a key-wrapping key.
+ */
+function wrapCEK(cek, wrappingKey) {
+  return aesWrap(wrappingKey, cek);
+}
+
+/**
+ * Unwrap a CEK from its wrapped form.
+ */
+function unwrapCEK(wrappedCek, wrappingKey) {
+  return aesUnwrap(wrappingKey, wrappedCek);
+}
+
+/**
+ * Encrypt a licensed entry using the RFC-0008 compliant model.
+ *
+ * 1. Generate random CEK
+ * 2. Derive KWK from license key + machine fingerprint via HKDF
+ * 3. Encrypt content with CEK (AES-256-GCM)
+ * 4. Wrap CEK with KWK (AES-256-KW)
+ * 5. Store wrapped_key in envelope
+ */
+function encryptLicensedEntryV1(plaintext, options = {}) {
+  const { entryName, manifest = {}, licenseKey } = options;
+  if (!entryName) throw new Error('entryName is required');
+  if (!licenseKey) throw new Error('licenseKey is required for RFC-0008 encryption');
+
+  const cek = generateCEK();
+  const wrappingKey = deriveWrappingKey(licenseKey);
+  const wrappedKey = wrapCEK(cek, wrappingKey);
+
+  const iv = crypto.randomBytes(12);
+  const cipher = crypto.createCipheriv('aes-256-gcm', cek, iv);
+  cipher.setAAD(encryptedEntryAad(entryName, manifest));
+  const ciphertext = Buffer.concat([cipher.update(toBuffer(plaintext, 'plaintext')), cipher.final()]);
+
+  return {
+    profile: LICENSED_ENTRY_PROFILE,
+    alg: ALG,
+    kdf: RFC_KDF,
+    key_wrapping: RFC_KEY_WRAPPING,
+    wrapped_key: wrappedKey.toString('base64'),
+    iv: iv.toString('base64'),
+    tag: cipher.getAuthTag().toString('base64'),
+    ciphertext: ciphertext.toString('base64'),
+  };
+}
+
+/**
+ * Decrypt a licensed entry encoded with the RFC-0008 compliant profile.
+ *
+ * 1. Derive KWK from license key via HKDF
+ * 2. Unwrap CEK from wrapped_key (AES-256-KW)
+ * 3. Decrypt content with CEK (AES-256-GCM)
+ */
+function decryptLicensedEntryV1(envelopeValue, options = {}) {
+  const { entryName, manifest = {}, licenseKey } = options;
+  if (!entryName) throw new Error('entryName is required');
+  if (!licenseKey) throw new Error('licenseKey is required for RFC-0008 decryption');
+
+  const envelope = normalizeEnvelope(envelopeValue);
+  if (envelope.profile !== LICENSED_ENTRY_PROFILE) {
+    throw new Error(`unsupported encrypted entry profile: ${envelope.profile || 'unknown'} (expected ${LICENSED_ENTRY_PROFILE})`);
+  }
+  if (envelope.alg !== ALG) throw new Error(`unsupported encrypted entry alg: ${envelope.alg}`);
+  if (envelope.kdf !== RFC_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}`);
+
+  const wrappingKey = deriveWrappingKey(licenseKey);
+  const cek = unwrapCEK(decodeBase64(envelope.wrapped_key, 'wrapped_key'), wrappingKey);
+
+  const decipher = crypto.createDecipheriv('aes-256-gcm', cek, decodeBase64(envelope.iv, 'iv'));
+  decipher.setAAD(encryptedEntryAad(entryName, manifest));
+  decipher.setAuthTag(decodeBase64(envelope.tag, 'tag'));
+  return Buffer.concat([
+    decipher.update(decodeBase64(envelope.ciphertext, 'ciphertext')),
+    decipher.final(),
+  ]);
+}
+
+// ── Legacy / experimental profile (pre-RFC, backward compat) ───────
+
+function deriveLicensedEntryKeyLegacy(options = {}) {
+  const { licenseKey, machineFingerprint, salt, keyLength = 32 } = options;
+  if (!licenseKey) throw new Error('licenseKey is required');
+  if (!machineFingerprint) throw new Error('machineFingerprint is required');
+  const saltBuffer = Buffer.isBuffer(salt) || salt instanceof Uint8Array
+    ? Buffer.from(salt)
+    : decodeBase64(salt, 'salt');
+  const secret = `${licenseKey}|${machineFingerprint}`;
+  return crypto.scryptSync(secret, saltBuffer, keyLength);
+}
+
+function encryptLicensedEntryLegacy(plaintext, options = {}) {
   const { entryName, manifest = {}, licenseKey, machineFingerprint } = options;
   if (!entryName) throw new Error('entryName is required');
   const salt = crypto.randomBytes(16);
   const iv = crypto.randomBytes(12);
-  const key = deriveLicensedEntryKey({ licenseKey, machineFingerprint, salt });
+  const key = deriveLicensedEntryKeyLegacy({ licenseKey, machineFingerprint, salt });
   const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
-  cipher.setAAD(encryptedEntryAad(entryName, manifest));
+  cipher.setAAD(encryptedEntryAad(entryName, manifest, LICENSED_EXPERIMENTAL_PROFILE));
   const ciphertext = Buffer.concat([cipher.update(toBuffer(plaintext, 'plaintext')), cipher.final()]);
   return {
-    profile: LICENSED_ENTRY_PROFILE,
+    profile: LICENSED_EXPERIMENTAL_PROFILE,
     alg: ALG,
-    kdf: KDF,
+    kdf: LEGACY_KDF,
     salt: salt.toString('base64'),
     iv: iv.toString('base64'),
     tag: cipher.getAuthTag().toString('base64'),
@@ -68,22 +279,22 @@ function encryptLicensedEntry(plaintext, options = {}) {
   };
 }
 
-function decryptLicensedEntry(envelopeValue, options = {}) {
+function decryptLicensedEntryLegacy(envelopeValue, options = {}) {
   const { entryName, manifest = {}, licenseKey, machineFingerprint } = options;
   if (!entryName) throw new Error('entryName is required');
   const envelope = normalizeEnvelope(envelopeValue);
-  if (envelope.profile !== LICENSED_ENTRY_PROFILE) {
+  if (envelope.profile !== LICENSED_EXPERIMENTAL_PROFILE) {
     throw new Error(`unsupported encrypted entry profile: ${envelope.profile || 'unknown'}`);
   }
   if (envelope.alg !== ALG) throw new Error(`unsupported encrypted entry alg: ${envelope.alg}`);
-  if (envelope.kdf !== KDF) throw new Error(`unsupported encrypted entry kdf: ${envelope.kdf}`);
-  const key = deriveLicensedEntryKey({
+  if (envelope.kdf !== LEGACY_KDF) throw new Error(`unsupported encrypted entry kdf: ${envelope.kdf}`);
+  const key = deriveLicensedEntryKeyLegacy({
     licenseKey,
     machineFingerprint,
     salt: envelope.salt,
   });
   const decipher = crypto.createDecipheriv('aes-256-gcm', key, decodeBase64(envelope.iv, 'iv'));
-  decipher.setAAD(encryptedEntryAad(entryName, manifest));
+  decipher.setAAD(encryptedEntryAad(entryName, manifest, LICENSED_EXPERIMENTAL_PROFILE));
   decipher.setAuthTag(decodeBase64(envelope.tag, 'tag'));
   return Buffer.concat([
     decipher.update(decodeBase64(envelope.ciphertext, 'ciphertext')),
@@ -91,6 +302,23 @@ function decryptLicensedEntry(envelopeValue, options = {}) {
   ]);
 }
 
+// ── Unified entry points (auto-detect profile) ────────────────────
+
+function encryptLicensedEntry(plaintext, options = {}) {
+  return encryptLicensedEntryV1(plaintext, options);
+}
+
+function decryptLicensedEntry(envelopeValue, options = {}) {
+  const envelope = normalizeEnvelope(envelopeValue);
+  if (envelope.profile === LICENSED_ENTRY_PROFILE) {
+    return decryptLicensedEntryV1(envelopeValue, options);
+  }
+  if (envelope.profile === LICENSED_EXPERIMENTAL_PROFILE) {
+    return decryptLicensedEntryLegacy(envelopeValue, options);
+  }
+  throw new Error(`unsupported encrypted entry profile: ${envelope.profile || 'unknown'}`);
+}
+
 function createLicensedDecryptEntry(options = {}) {
   const { licenseKey, machineFingerprint } = options;
   return ({ entryName, ciphertext, manifest }) =>
@@ -98,9 +326,34 @@ function createLicensedDecryptEntry(options = {}) {
 }
 
 module.exports = {
+  // Profiles
   LICENSED_ENTRY_PROFILE,
-  deriveLicensedEntryKey,
+  LICENSED_EXPERIMENTAL_PROFILE,
+  ALG,
+  RFC_KDF,
+  RFC_KEY_WRAPPING,
+  LEGACY_KDF,
+
+  // RFC-0008 compliant
+  deriveWrappingKey,
+  generateCEK,
+  wrapCEK,
+  unwrapCEK,
+  encryptLicensedEntryV1,
+  decryptLicensedEntryV1,
+
+  // Legacy
+  deriveLicensedEntryKey: deriveLicensedEntryKeyLegacy,
+  encryptLicensedEntryLegacy,
+  decryptLicensedEntryLegacy,
+
+  // Unified
   encryptLicensedEntry,
   decryptLicensedEntry,
   createLicensedDecryptEntry,
+
+  // Low-level
+  hkdfSha256,
+  aesWrap,
+  aesUnwrap,
 };

package/src/index.js

@@ -8,8 +8,10 @@ const render = require('./render');
 const compose = require('./compose');
 const assetReader = require('./asset-reader');
 const cryptoProfile = require('./crypto-profile');
+const publicApi = require('./public-api');
 
 module.exports = {
+  ...publicApi,
   ...loader,
   ...lint,
   ...validate,

package/src/lint-pure.js

@@ -261,11 +261,20 @@ const VALID_BADGE = new Set(['untested', 'tested', 'validated', 'expert_reviewed
 const VALID_ACCESS = new Set(['open', 'licensed', 'runtime']);
 const VALID_RISK = new Set(['R0', 'R1', 'R2', 'R3']);
 const VALID_I18N = new Set(['L0', 'L1', 'L2', 'L3']);
+const VALID_PRIVACY = new Set(['public', 'private', 'sensitive', 'regulated']);
+const VALID_ASSET_TYPE = new Set([
+  'domain_judgment',
+  'personal_judgment',
+  'organization_standard',
+  'team_policy',
+  'creator_style',
+  'risk_guard',
+]);
 
 const MANIFEST_REQUIRED = [
-  'kdna_spec', 'name', 'version', 'judgment_version',
-  'description', 'author', 'license', 'status',
-  'quality_badge', 'access', 'language',
+  'format', 'format_version', 'spec_version', 'name', 'version',
+  'judgment_version', 'description', 'author', 'license', 'status',
+  'quality_badge', 'access', 'languages', 'default_language',
 ];
 
 /**
@@ -283,13 +292,15 @@ function validateManifest(manifest) {
     return { errors, warnings };
   }
 
-  // 1. Check spec_version is NOT in domain manifest (use kdna_spec only)
-  if ('spec_version' in manifest) {
+  // 1. Check disallowed pre-v1.0 manifest aliases
+  if ('kdna_spec' in manifest) {
     errors.push(
-      'kdna.json: spec_version is deprecated in domain manifests. Use kdna_spec. ' +
-      '(spec_version is reserved for .kdna container manifests only.)',
+      'kdna.json: kdna_spec is not allowed. Use spec_version.',
     );
   }
+  if ('language' in manifest) {
+    errors.push('kdna.json: language is not allowed. Use default_language and languages.');
+  }
 
   // 2. Check required fields
   for (const field of MANIFEST_REQUIRED) {
@@ -304,6 +315,14 @@ function validateManifest(manifest) {
   }
 
   // 4. Validate enum fields
+  if (manifest.format && manifest.format !== 'kdna') {
+    errors.push(`kdna.json.format: invalid value "${manifest.format}". Expected "kdna".`);
+  }
+  if (manifest.format_version && manifest.format_version !== '1.0') {
+    errors.push(
+      `kdna.json.format_version: invalid value "${manifest.format_version}". Expected "1.0".`,
+    );
+  }
   if (manifest.status && !VALID_STATUS.has(manifest.status)) {
     errors.push(
       `kdna.json.status: invalid value "${manifest.status}". ` +
@@ -334,6 +353,18 @@ function validateManifest(manifest) {
       `Valid: ${[...VALID_I18N].join(', ')}`,
     );
   }
+  if (manifest.privacy_level && !VALID_PRIVACY.has(manifest.privacy_level)) {
+    warnings.push(
+      `kdna.json.privacy_level: non-standard value "${manifest.privacy_level}". ` +
+      `Valid: ${[...VALID_PRIVACY].join(', ')}`,
+    );
+  }
+  if (manifest.asset_type && !VALID_ASSET_TYPE.has(manifest.asset_type)) {
+    warnings.push(
+      `kdna.json.asset_type: non-standard value "${manifest.asset_type}". ` +
+      `Valid: ${[...VALID_ASSET_TYPE].join(', ')}`,
+    );
+  }
 
   // 5. Deprecated status must have replaced_by
   if (manifest.status === 'deprecated' && !manifest.replaced_by) {
@@ -362,10 +393,10 @@ function validateManifest(manifest) {
     errors.push('kdna.json.license: missing "type"');
   }
 
-  // 9. Validate kdna_spec value
-  if (manifest.kdna_spec && manifest.kdna_spec !== '1.0-rc') {
+  // 9. Validate spec_version value
+  if (manifest.spec_version && manifest.spec_version !== '1.0-rc') {
     warnings.push(
-      `kdna.json.kdna_spec: non-standard value "${manifest.kdna_spec}". Expected "1.0-rc".`,
+      `kdna.json.spec_version: non-standard value "${manifest.spec_version}". Expected "1.0-rc".`,
     );
   }