@aikdna/kdna-core 0.14.0 → 0.15.1

package/CHANGELOG.md

@@ -0,0 +1,107 @@
+# Changelog
+
+## v0.15.1 (2026-06-27)
+- Fix: package.json `files` array now includes `CHANGELOG.md`. The
+  v0.15.0 tarball was published without the changelog, leaving
+  consumers with no way to read release notes from `npm install`.
+  Adding it now is a no-op for code but resolves the docs gap.
+
+## v0.15.0 (2026-06-27)
+- B2: scrypt password profile `kdna-password-protected-v1-scrypt` (ADR-007)
+  - encryptProtectedEntryScrypt / decryptProtectedEntryScrypt (zero new deps, Node crypto.scryptSync)
+  - AES-256-GCM + AES-256-KW envelope encryption, same CEK model as RFC-0008
+  - scrypt N=32768 r=8 p=1, 32B KEK, 16B random salt
+  - planLoad inferEntitlementProfile detects scrypt profile
+  - decrypt dispatch routes Argon2id vs scrypt by envelope profile field
+  - recovery slot deferred to v0.2; v0.1: single password slot
+- B5: conformance:canonical npm script (threshold #8)
+
+## v0.14.0 (2026-06-25)
+- B1: unified container dispatcher (readAsset — v1/v2/ dir → CanonicalAssetModel)
+- B4: loadAuthorized decryption orchestration (opts.password, opts.decryptEntry)
+- B4: encrypted payload detection in runValidate (backward compatible)
+- B8: cross-language golden vectors (test-vectors/golden-vectors.js — 8/8)
+- Wave 4: canonical conformance (conformance/canonical-conformance.mjs — 13/13)
+- Wave 2.5: clear deprecated registry/domains.json private entries
+- Wave 3a: CQ-T2/T3 symmetric compact rendering, scenario null consistency
+- Add: engines.node >=18.0.0
+
+## v0.13.3 (2026-06-22)
+- Fix: index profile includes max_tokens_hint
+- Fix: compact profile falls back to full_statement for TBD placeholders
+
+Packages: `@aikdna/kdna-core`
+
+## v0.13.2 (2026-06-21)
+
+### Fixed
+- Compact boundary projection now correctly preserves `applies_when`, `does_not_apply_when`, and `failure_risk` fields across all load profiles. These axiom governance fields are required by `kdna-loader` for domain routing decisions and were being dropped in compact mode under certain manifest configurations.
+- Cross-platform test stability: Node test glob patterns are now compatible with both macOS and Linux filesystem sort orders.
+- Hash library compatibility: `@noble/hashes` replaces Node-only crypto for digest operations, maintaining Node 18 compatibility without native module binding requirements.
+
+### Changed
+- Public API boundary hardened: `loadKDNA`, `loadKDNASync`, `inspectKDNA`, and `inspectKDNASync` now enforce the asset-first contract — callers must pass `.kdna` files or asset handles, not raw directory paths.
+- Examples in README and inline docs reference the packaged `.kdna` path rather than source directories.
+- First-run contract tightened: exported symbols, error codes, and validation gate names are now part of the stable API surface.
+
+---
+
+## v0.13.1 (2026-06-21)
+
+### Fixed
+- **Compact boundary projection preserved.** The `planLoad` function and `loadAuthorized` shim now pass through the full axiom governance projection (applies_when, does_not_apply_when, failure_risk) even when the load contract is not present in the manifest. Prior versions could strip these fields under compact profile, breaking domain routing for `kdna-loader`.
+- Digest matching now tolerates `sha256:` prefix in both `manifest_digest` and `payload_digest` checksums entries. Previously, a leading `sha256:` prefix was treated as part of the hex digest, causing false mismatches.
+
+### Changed
+- Public API provenance and profile split clarified: `loadKDNA` / `loadKDNASync` are the stable entry points for runtime consumers. Lower-level `readV1Layout`, `runValidate`, and `planLoad` are exported for advanced tooling but carry no backward-compatibility guarantee.
+- Access enum values normalized everywhere: `public`, `licensed`, `remote`. Legacy aliases (`open` → `public`, `protected` → `licensed`, `runtime` → `remote`) are mapped transparently with an info-level issue in the LoadPlan.
+- `verifyAsset` / `verifyAssetSync`, `verifyDigest` / `verifyDigestSync`, and `verifySignature` / `verifySignatureSync` are now documented as the stable verification API surface.
+
+---
+
+## v0.13.0 (2026-06-19)
+
+### Added
+- **Authorization LoadPlan contract.** The `planLoad(inputPath, opts)` function returns a structured LoadPlan before any judgment content is decrypted or emitted. The LoadPlan reports:
+  - `asset_id`, `asset_uid`, `title`, `version`, `judgment_version`
+  - `access` model (`public` | `licensed` | `remote`)
+  - `entitlement_profile` (`password`, `local_receipt`, `account`, `org`, `purchase_receipt`, `device_bound`)
+  - `state` (`ready` | `needs_password` | `needs_license` | `needs_account` | `needs_org_auth` | `expired_grace` | `offline_grace` | `denied` | `invalid` | `needs_runtime`)
+  - `required_action` (`load` | `enter_password` | `install_receipt` | `sign_in_or_activate` | `renew_entitlement` | `sync` | `contact_issuer` | `connect_runtime` | `block`)
+  - `can_load_now` boolean — the single decision point for product consumers
+  - `projection_policy` (`none` | `minimal` | `remote`)
+  - `checks` block with per-gate validation results
+  - `issues` array with structured error codes (`KDNA_FORMAT_INVALID`, `KDNA_INTEGRITY_DIGEST_FAILED`, `KDNA_AUTH_PASSWORD_REQUIRED`, `KDNA_AUTH_ENTITLEMENT_REQUIRED`, `KDNA_ACCESS_MODE_UNKNOWN`, etc.)
+  - `input_fingerprint` capturing the source digest, has-password signal, and entitlement status for cache keying
+  - `source.kind` and `source.path` indicating whether the input was a source directory or `.kdna` container
+- **`loadAuthorized(inputPath, opts)`** — a higher-level loader that calls `planLoad` first and blocks load when `can_load_now` is false. Throws `KDNA_LOAD_NOT_AUTHORIZED` with the first issue's code. This is the recommended entry point for agent runtimes.
+- **`loadV1(inputPath, opts)`** — renders judgment content into agent-ready prompt text. Supports profiles (`index`, `compact`, `scenario`, `full`) and output formats (`json`, `prompt`). The `prompt` format produces a flat text block suitable for agent context windows with proper axiom applicability rendering.
+- **KDNA Core v1 inspect module.** `inspect(inputPath)` returns a content-neutral manifest summary including `asset_id`, `asset_uid`, `kdna_version`, `payload_encrypted`, `profile`, `load_contract_default_profile`, and signature count. Output is always JSON. Banned terms (`trusted`, `recommended`, `high_quality`, `officially_approved`) are enforced by an automatic assertion.
+- **KDNA Core v1 validate module.** `validate(inputPath)` runs four independent gates:
+  1. **Format gate:** required entries present (`mimetype`, `kdna.json`, `payload.kdnab`), mimetype content correct, lineage is an object not an array
+  2. **Schema gate:** `kdna.json` against `manifest.schema.json` via AJV 2020-12
+  3. **Payload gate:** `payload.kdnab` against `payload-profile-v1.schema.json`
+  4. **Checksums gate:** when `checksums.json` is present, computed digests are compared against declared values for `kdna.json`, `payload.kdnab`, and the combined asset digest
+- **KDNA Core v1 pack module.** `pack(sourceDir, outputPath)` produces a deterministic `.kdna` container: fixed DOS epoch timestamps, alphabetical entry order, mimetype first (STORED, method 0). Same source → byte-identical output.
+- **KDNA Core v1 unpack module.** `unpack(inputPath, outputDir)` extracts a `.kdna` container to a directory with path-traversal protection.
+- **Container security hardening.** ZIP reader enforces:
+  - Maximum container size (25 MiB), max entries (128), max entry size (5 MiB), max total uncompressed (12 MiB)
+  - Max compression ratio (100:1) to prevent zip bombs
+  - Max JSON depth (64), max array length (10,000), max string length (1 MiB)
+  - Entry name normalization (NFC Unicode, no backslash separators, no absolute paths, no `..` traversal)
+  - Duplicate entry rejection
+  - Symlink and device/special file rejection
+- **Digest matching verification.** When `checksums.json` includes `manifest_digest`, `payload_digest`, or `asset_digest`, the validate module computes actual SHA-256 hashes and compares them. Mismatch produces a `KDNA_INTEGRITY_DIGEST_FAILED` issue.
+- **Load contract validation.** When the manifest includes a `load_contract` block, it is validated against `load-contract.schema.json`. A missing load contract is not an error — it simply means no specialization.
+- **Dual CJS/ESM exports.** `src/index.js` (CommonJS) and `src/index.mjs` (ES module) with matching `exports` map. The v1 module is also available at `@aikdna/kdna-core/v1`.
+- **TypeScript declarations.** `src/types.d.ts` exports type definitions for the stable public API surface.
+
+### Changed
+- **V1 is the only active format path.** The v2 reader (`readDataMapSync`, `readDataMap`) remains in the codebase for migration compatibility but is no longer the default path. All new integrations should use the v1 API: `inspect`, `validate`, `planLoad`, `loadAuthorized`.
+- `validate` and `planLoad` reject v2 containers (`application/vnd.aikdna.kdna+zip`) with a format error.
+- Access model normalized to the three-tier `public` | `licensed` | `remote` enum. The LoadPlan maps legacy values transparently with an info-level issue.
+- Container format detection (`detectContainerFormat`) reads only the first central-directory entry to determine v1 vs v2, preventing malicious later entries from causing format confusion.
+
+### Removed
+- Legacy v1 compatibility shims removed. v2 is the only legacy format and is handled through the existing `asset-reader.js` module.
+- `readDataMapSync` / `readDataMap` deprecated for new use. Use `planLoad` + `loadV1` for runtime loading or `validate` + `inspect` for diagnostics.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aikdna/kdna-core",
-  "version": "0.14.0",
+  "version": "0.15.1",
   "description": "KDNA Core library for validating, planning, and loading local .kdna judgment assets.",
   "engines": {
     "node": ">=18.0.0"
@@ -25,13 +25,14 @@
   "types": "src/types.d.ts",
   "scripts": {
     "test": "node ../../scripts/run-node-tests.js test/*.test.js && node -e \"const m = require('./src/index.js'); console.log('kdna-core exports:', Object.keys(m).join(', '));\"",
-    "prepublishOnly": "npm run release:check && npm --prefix ../.. run ecosystem-gate",
+    "prepublishOnly": "npm run release:check",
     "release:check": "node scripts/check-release-readiness.js"
   },
   "files": [
     "src/",
     "schema/",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE",
     "NOTICE"
   ],

package/src/crypto-profile.js

@@ -420,6 +420,121 @@ function createRecoveryDecryptEntry(options = {}) {
     decryptProtectedEntry(ciphertext, { entryName, manifest, recoveryCode });
 }
 
+// ── B2: scrypt-based password profile (v0.1 write profile) ─────────
+// Uses Node built-in crypto.scryptSync — zero additional dependencies.
+// v0.2 will promote the Argon2id profile (above) as the default write
+// profile; this scrypt profile will remain a read-only legacy profile.
+
+const PASSWORD_PROTECTED_SCRYPT_PROFILE = 'kdna-password-protected-v1-scrypt';
+const SCRYPT_KDF = 'scrypt-sha256';
+
+function derivePasswordKeyScrypt(password, params = {}) {
+  const { salt, N = 32768, r = 8, p = 1 } = params;
+  if (!salt) throw new Error('salt is required for scrypt KDF');
+  const saltBuf = decodeBase64(salt, 'salt');
+  const passwordBuf = toBuffer(password, 'password');
+  // N=32768, r=8, p=1 → 32 MiB memory. Default maxmem is 32 MiB exactly;
+  // bump to 64 MiB to avoid boundary rejection on some Node versions.
+  return crypto.scryptSync(passwordBuf, saltBuf, 32, { N, r, p, maxmem: 64 * 1024 * 1024 });
+}
+
+/**
+ * Encrypt a protected entry using the scrypt-based password profile.
+ *
+ * 1. Generate random CEK (32 bytes)
+ * 2. Derive KEK from password via scrypt-sha256
+ * 3. Encrypt content with CEK (AES-256-GCM)
+ * 4. Wrap CEK with KEK (AES-256-KW)
+ * 5. Store wrapped_key in envelope (single password slot, no recovery)
+ */
+function encryptProtectedEntryScrypt(plaintext, options = {}) {
+  const { entryName, manifest = {}, password } = options;
+  if (!entryName) throw new Error('entryName is required');
+  if (!password) throw new Error('password is required for scrypt encryption');
+
+  const cek = generateCEK();
+
+  // Password slot
+  const salt = crypto.randomBytes(16);
+  const passwordKey = derivePasswordKeyScrypt(password, { salt: salt.toString('base64') });
+  const passwordWrappedKey = wrapCEK(cek, passwordKey);
+
+  const iv = crypto.randomBytes(12);
+  const cipher = crypto.createCipheriv('aes-256-gcm', cek, iv);
+  cipher.setAAD(encryptedEntryAad(entryName, manifest, PASSWORD_PROTECTED_SCRYPT_PROFILE));
+  const ciphertext = Buffer.concat([cipher.update(toBuffer(plaintext, 'plaintext')), cipher.final()]);
+
+  return {
+    profile: PASSWORD_PROTECTED_SCRYPT_PROFILE,
+    alg: ALG,
+    kdf: SCRYPT_KDF,
+    key_wrapping: RFC_KEY_WRAPPING,
+    scrypt_params: {
+      N: 32768,
+      r: 8,
+      p: 1,
+      salt: salt.toString('base64'),
+    },
+    key_slots: [
+      {
+        slot: 'password',
+        wrap: RFC_KEY_WRAPPING,
+        wrapped_key: passwordWrappedKey.toString('base64'),
+      },
+    ],
+    iv: iv.toString('base64'),
+    tag: cipher.getAuthTag().toString('base64'),
+    ciphertext: ciphertext.toString('base64'),
+  };
+}
+
+/**
+ * Decrypt a protected entry encoded with the scrypt-based password profile.
+ *
+ * 1. Derive KEK from password via scrypt-sha256
+ * 2. Unwrap CEK from password slot's wrapped_key (AES-256-KW)
+ * 3. Decrypt content with CEK (AES-256-GCM)
+ */
+function decryptProtectedEntryScrypt(envelopeValue, options = {}) {
+  const { entryName, manifest = {}, password } = options;
+  if (!entryName) throw new Error('entryName is required');
+  if (!password) throw new Error('password is required for scrypt decryption');
+
+  const envelope = normalizeEnvelope(envelopeValue);
+  if (envelope.profile !== PASSWORD_PROTECTED_SCRYPT_PROFILE) {
+    throw new Error(
+      `unsupported encrypted entry profile: ${envelope.profile || 'unknown'} (expected ${PASSWORD_PROTECTED_SCRYPT_PROFILE})`,
+    );
+  }
+  if (envelope.alg !== ALG) throw new Error(`unsupported encrypted entry alg: ${envelope.alg}`);
+  if (envelope.kdf !== SCRYPT_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 passwordKey = derivePasswordKeyScrypt(password, {
+    salt: envelope.scrypt_params.salt,
+  });
+  const passwordSlot = envelope.key_slots.find((s) => s.slot === 'password');
+  if (!passwordSlot) throw new Error('password slot missing from envelope');
+
+  const cek = unwrapCEK(decodeBase64(passwordSlot.wrapped_key, 'wrapped_key'), passwordKey);
+
+  const decipher = crypto.createDecipheriv('aes-256-gcm', cek, decodeBase64(envelope.iv, 'iv'));
+  decipher.setAAD(encryptedEntryAad(entryName, manifest, PASSWORD_PROTECTED_SCRYPT_PROFILE));
+  decipher.setAuthTag(decodeBase64(envelope.tag, 'tag'));
+  return Buffer.concat([
+    decipher.update(decodeBase64(envelope.ciphertext, 'ciphertext')),
+    decipher.final(),
+  ]);
+}
+
+function createPasswordDecryptEntryScrypt(options = {}) {
+  const { password } = options;
+  return ({ entryName, ciphertext, manifest }) =>
+    decryptProtectedEntryScrypt(ciphertext, { entryName, manifest, password });
+}
+
 // ── Legacy / experimental profile (pre-RFC, backward compat) ───────
 
 function deriveLicensedEntryKeyLegacy(options = {}) {
@@ -504,11 +619,13 @@ module.exports = {
   LICENSED_ENTRY_PROFILE,
   LICENSED_EXPERIMENTAL_PROFILE,
   PASSWORD_PROTECTED_PROFILE,
+  PASSWORD_PROTECTED_SCRYPT_PROFILE,
   ALG,
   RFC_KDF,
   RFC_KEY_WRAPPING,
   LEGACY_KDF,
   PASSWORD_KDF,
+  SCRYPT_KDF,
 
   // RFC-0008 compliant
   deriveWrappingKey,
@@ -518,7 +635,7 @@ module.exports = {
   encryptLicensedEntryV1,
   decryptLicensedEntryV1,
 
-  // RFC-0009 compliant
+  // RFC-0009 compliant (Argon2id)
   derivePasswordKey,
   generateRecoveryCode,
   decodeRecoveryCode,
@@ -527,6 +644,12 @@ module.exports = {
   createPasswordDecryptEntry,
   createRecoveryDecryptEntry,
 
+  // B2 scrypt password profile (v0.1 write profile)
+  derivePasswordKeyScrypt,
+  encryptProtectedEntryScrypt,
+  decryptProtectedEntryScrypt,
+  createPasswordDecryptEntryScrypt,
+
   // Legacy
   deriveLicensedEntryKey: deriveLicensedEntryKeyLegacy,
   encryptLicensedEntryLegacy,

package/src/v1/index.js

@@ -1014,6 +1014,9 @@ function inferEntitlementProfile(manifest) {
   if (manifest.encryption && manifest.encryption.profile === 'kdna-password-protected-v1') {
     return 'password';
   }
+  if (manifest.encryption && manifest.encryption.profile === 'kdna-password-protected-v1-scrypt') {
+    return 'password';
+  }
   if (manifest.access === 'protected') return 'password';
   return null;
 }
@@ -1609,11 +1612,20 @@ function loadV1Unsafe(inputPath, opts = {}) {
         throw err;
       }
     } else if (opts.password) {
-      // Password-based decryption via kdna-password-protected-v1 profile
+      // Password-based decryption via kdna-password-protected-v1*
+      // profiles. Detects Argon2id vs scrypt from the envelope profile.
       try {
-        const { decryptProtectedEntry } = require('../crypto-profile.js');
+        const {
+          decryptProtectedEntry,
+          decryptProtectedEntryScrypt,
+          PASSWORD_PROTECTED_SCRYPT_PROFILE,
+        } = require('../crypto-profile.js');
         const encryptedEnvelope = v1.map['payload.kdnab'].toString('utf8');
-        const decryptedBuf = decryptProtectedEntry(encryptedEnvelope, {
+        const envelope = JSON.parse(encryptedEnvelope);
+        const decryptFn = (envelope.profile === PASSWORD_PROTECTED_SCRYPT_PROFILE)
+          ? decryptProtectedEntryScrypt
+          : decryptProtectedEntry;
+        const decryptedBuf = decryptFn(encryptedEnvelope, {
           entryName: 'payload.kdnab',
           manifest: m,
           password: opts.password,