@aikdna/kdna-core 0.4.0 → 0.6.0

package/src/crypto-profile.js

@@ -0,0 +1,106 @@
+const crypto = require('crypto');
+
+const LICENSED_ENTRY_PROFILE = 'kdna-licensed-entry-v1';
+const KDF = 'scrypt-sha256';
+const ALG = 'AES-256-GCM';
+
+function toBuffer(value, label) {
+  if (Buffer.isBuffer(value)) return value;
+  if (value instanceof Uint8Array) return Buffer.from(value);
+  if (typeof value === 'string') return Buffer.from(value, 'utf8');
+  throw new Error(`${label} must be a string, Buffer, or Uint8Array`);
+}
+
+function decodeBase64(value, label) {
+  if (typeof value !== 'string' || !value) throw new Error(`${label} must be base64`);
+  return Buffer.from(value, 'base64');
+}
+
+function normalizeEnvelope(value) {
+  if (Buffer.isBuffer(value) || value instanceof Uint8Array) {
+    return JSON.parse(Buffer.from(value).toString('utf8'));
+  }
+  if (typeof value === 'string') return JSON.parse(value);
+  if (value && typeof value === 'object') return 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 = {}) {
+  return Buffer.from(
+    [
+      LICENSED_ENTRY_PROFILE,
+      manifest.name || manifest.asset_id || '',
+      manifest.version || '',
+      entryName,
+    ].join('\n'),
+    'utf8',
+  );
+}
+
+function encryptLicensedEntry(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 cipher = crypto.createCipheriv('aes-256-gcm', key, 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: KDF,
+    salt: salt.toString('base64'),
+    iv: iv.toString('base64'),
+    tag: cipher.getAuthTag().toString('base64'),
+    ciphertext: ciphertext.toString('base64'),
+  };
+}
+
+function decryptLicensedEntry(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) {
+    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({
+    licenseKey,
+    machineFingerprint,
+    salt: envelope.salt,
+  });
+  const decipher = crypto.createDecipheriv('aes-256-gcm', key, 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(),
+  ]);
+}
+
+function createLicensedDecryptEntry(options = {}) {
+  const { licenseKey, machineFingerprint } = options;
+  return ({ entryName, ciphertext, manifest }) =>
+    decryptLicensedEntry(ciphertext, { entryName, manifest, licenseKey, machineFingerprint });
+}
+
+module.exports = {
+  LICENSED_ENTRY_PROFILE,
+  deriveLicensedEntryKey,
+  encryptLicensedEntry,
+  decryptLicensedEntry,
+  createLicensedDecryptEntry,
+};

package/src/index.js

@@ -6,11 +6,17 @@ const lint = require('./lint-pure');
 const validate = require('./validate-pure');
 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,
   ...render,
   ...compose,
+  ...assetReader,
+  ...cryptoProfile,
 };

package/src/index.mjs

@@ -17,3 +17,14 @@ export { validateDomainSchema, validateCrossFile } from './validate-pure.js';
 export { renderPreviewHTML, escHtml, renderCard } from './render.js';
 
 export { composeContext, composeContextWithAttribution, classifySignals, classifySignalsAcrossDomains, composeChecks, loadAndCompose, loadCluster, detectDomainConflicts, generateClusterTrace } from './compose.js';
+
+import assetReader from './asset-reader.js';
+import cryptoProfile from './crypto-profile.js';
+
+export const STANDARD_ENTRIES = assetReader.STANDARD_ENTRIES;
+export const createKdnaAssetReader = assetReader.createKdnaAssetReader;
+export const LICENSED_ENTRY_PROFILE = cryptoProfile.LICENSED_ENTRY_PROFILE;
+export const deriveLicensedEntryKey = cryptoProfile.deriveLicensedEntryKey;
+export const encryptLicensedEntry = cryptoProfile.encryptLicensedEntry;
+export const decryptLicensedEntry = cryptoProfile.decryptLicensedEntry;
+export const createLicensedDecryptEntry = cryptoProfile.createLicensedDecryptEntry;

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".`,
     );
   }
 

package/src/public-api.js

@@ -0,0 +1,323 @@
+/**
+ * Stable public API for third-party KDNA integrations.
+ *
+ * Lower-level modules remain exported for advanced runtimes, but external
+ * adapters should prefer these names. They encode the asset-first contract:
+ * callers pass .kdna files or bytes, and no persistent directory extraction is
+ * required.
+ */
+
+const { createKdnaAssetReader } = require('./asset-reader');
+const { lintDomain } = require('./lint-pure');
+const { validateCrossFile, validateDomainSchema } = require('./validate-pure');
+const { formatContext } = require('./loader');
+const {
+  composeContextWithAttribution,
+  detectDomainConflicts,
+  classifySignalsAcrossDomains,
+  generateClusterTrace,
+} = require('./compose');
+
+function readerFrom(options = {}) {
+  return options.reader || createKdnaAssetReader();
+}
+
+function isAsset(value) {
+  return value && typeof value === 'object' && value.entries instanceof Map && typeof value.readEntry === 'function';
+}
+
+async function asAsset(input, options = {}) {
+  if (isAsset(input)) return input;
+  return readerFrom(options).open(input);
+}
+
+function asAssetSync(input, options = {}) {
+  if (isAsset(input)) return input;
+  return readerFrom(options).openSync(input);
+}
+
+async function openKDNA(input, options = {}) {
+  return asAsset(input, options);
+}
+
+function openKDNASync(input, options = {}) {
+  return asAssetSync(input, options);
+}
+
+async function inspectKDNA(input, options = {}) {
+  const reader = readerFrom(options);
+  const asset = await asAsset(input, { ...options, reader });
+  const profile = await reader.loadProfile(asset, 'index', options);
+  const verification = options.verify === false ? null : await reader.verify(asset, options);
+  return {
+    name: profile.name,
+    version: profile.version,
+    judgment_version: profile.judgment_version,
+    access: profile.manifest.access || 'open',
+    status: profile.manifest.status || null,
+    quality_badge: profile.manifest.quality_badge || null,
+    risk_level: profile.manifest.risk_level || null,
+    keywords: profile.keywords,
+    entries: profile.entries,
+    asset_digest: profile.asset_digest,
+    content_digest: profile.content_digest,
+    signature_valid: verification ? verification.signature_valid : null,
+    ok: verification ? verification.ok : null,
+    errors: verification ? verification.errors : [],
+    warnings: verification ? verification.warnings : [],
+    manifest: profile.manifest,
+  };
+}
+
+function inspectKDNASync(input, options = {}) {
+  const reader = readerFrom(options);
+  const asset = asAssetSync(input, { ...options, reader });
+  const profile = reader.loadProfileSync(asset, 'index', options);
+  const verification = options.verify === false ? null : reader.verifySync(asset, options);
+  return {
+    name: profile.name,
+    version: profile.version,
+    judgment_version: profile.judgment_version,
+    access: profile.manifest.access || 'open',
+    status: profile.manifest.status || null,
+    quality_badge: profile.manifest.quality_badge || null,
+    risk_level: profile.manifest.risk_level || null,
+    keywords: profile.keywords,
+    entries: profile.entries,
+    asset_digest: profile.asset_digest,
+    content_digest: profile.content_digest,
+    signature_valid: verification ? verification.signature_valid : null,
+    ok: verification ? verification.ok : null,
+    errors: verification ? verification.errors : [],
+    warnings: verification ? verification.warnings : [],
+    manifest: profile.manifest,
+  };
+}
+
+async function loadKDNA(input, options = {}) {
+  const reader = readerFrom(options);
+  const asset = await asAsset(input, { ...options, reader });
+  return reader.loadProfile(asset, options.profile || 'compact', options);
+}
+
+function loadKDNASync(input, options = {}) {
+  const reader = readerFrom(options);
+  const asset = asAssetSync(input, { ...options, reader });
+  return reader.loadProfileSync(asset, options.profile || 'compact', options);
+}
+
+async function validateKDNA(input, options = {}) {
+  const reader = readerFrom(options);
+  const asset = await asAsset(input, { ...options, reader });
+  const assetResult = await reader.verify(asset, options);
+  let dataMap = null;
+  let lintResult = { errors: [], warnings: [] };
+  let schemaResult = { errors: [], warnings: [] };
+  let crossFileResult = { errors: [], warnings: [] };
+
+  try {
+    dataMap = await reader.readDataMap(asset, undefined, options);
+    lintResult = lintDomain(dataMap);
+    schemaResult = validateDomainSchema(dataMap, options.schemas || {});
+    crossFileResult = validateCrossFile(dataMap);
+  } catch (e) {
+    lintResult.errors.push(e.message);
+  }
+
+  const errors = [
+    ...assetResult.errors,
+    ...lintResult.errors,
+    ...schemaResult.errors,
+    ...crossFileResult.errors,
+  ];
+  const warnings = [
+    ...assetResult.warnings,
+    ...lintResult.warnings,
+    ...schemaResult.warnings,
+    ...crossFileResult.warnings,
+  ];
+  return {
+    ok: errors.length === 0,
+    errors,
+    warnings,
+    asset: assetResult,
+    lint: lintResult,
+    schema: schemaResult,
+    cross_file: crossFileResult,
+  };
+}
+
+function validateKDNASync(input, options = {}) {
+  const reader = readerFrom(options);
+  const asset = asAssetSync(input, { ...options, reader });
+  const assetResult = reader.verifySync(asset, options);
+  let lintResult = { errors: [], warnings: [] };
+  let schemaResult = { errors: [], warnings: [] };
+  let crossFileResult = { errors: [], warnings: [] };
+
+  try {
+    const dataMap = reader.readDataMapSync(asset, undefined, options);
+    lintResult = lintDomain(dataMap);
+    schemaResult = validateDomainSchema(dataMap, options.schemas || {});
+    crossFileResult = validateCrossFile(dataMap);
+  } catch (e) {
+    lintResult.errors.push(e.message);
+  }
+
+  const errors = [
+    ...assetResult.errors,
+    ...lintResult.errors,
+    ...schemaResult.errors,
+    ...crossFileResult.errors,
+  ];
+  const warnings = [
+    ...assetResult.warnings,
+    ...lintResult.warnings,
+    ...schemaResult.warnings,
+    ...crossFileResult.warnings,
+  ];
+  return {
+    ok: errors.length === 0,
+    errors,
+    warnings,
+    asset: assetResult,
+    lint: lintResult,
+    schema: schemaResult,
+    cross_file: crossFileResult,
+  };
+}
+
+async function renderForAgent(input, options = {}) {
+  const loaded = await loadKDNA(input, options);
+  if (loaded.context != null) return loaded.context;
+  return loaded.domain ? formatContext(loaded.domain) : '';
+}
+
+function renderForAgentSync(input, options = {}) {
+  const loaded = loadKDNASync(input, options);
+  if (loaded.context != null) return loaded.context;
+  return loaded.domain ? formatContext(loaded.domain) : '';
+}
+
+async function verifyAsset(input, options = {}) {
+  const reader = readerFrom(options);
+  const asset = await asAsset(input, { ...options, reader });
+  return reader.verify(asset, options);
+}
+
+function verifyAssetSync(input, options = {}) {
+  const reader = readerFrom(options);
+  const asset = asAssetSync(input, { ...options, reader });
+  return reader.verifySync(asset, options);
+}
+
+async function verifyDigest(input, expectedDigest, options = {}) {
+  return verifyAsset(input, { ...options, asset_digest: expectedDigest });
+}
+
+function verifyDigestSync(input, expectedDigest, options = {}) {
+  return verifyAssetSync(input, { ...options, asset_digest: expectedDigest });
+}
+
+async function verifySignature(input, options = {}) {
+  return verifyAsset(input, { ...options, requireSignature: true });
+}
+
+function verifySignatureSync(input, options = {}) {
+  return verifyAssetSync(input, { ...options, requireSignature: true });
+}
+
+function scoreMatch(input, info) {
+  const haystack = String(input || '').toLowerCase();
+  const terms = [
+    info.name,
+    ...(info.keywords || []),
+    info.manifest?.description,
+    info.manifest?.core_insight,
+  ]
+    .filter(Boolean)
+    .map((v) => String(v).toLowerCase());
+  const matched = terms.filter((term) => term && haystack.includes(term.replace(/^@[^/]+\//, '')));
+  return { score: matched.length, matched };
+}
+
+async function matchDomain(input, candidates, options = {}) {
+  const results = [];
+  for (const candidate of candidates || []) {
+    const info = typeof candidate === 'string' || candidate instanceof Uint8Array || isAsset(candidate)
+      ? await inspectKDNA(candidate, { ...options, verify: false })
+      : candidate;
+    const match = scoreMatch(input, info);
+    if (match.score > 0) results.push({ ...info, score: match.score, matched: match.matched });
+  }
+  return results.sort((a, b) => b.score - a.score || String(a.name).localeCompare(String(b.name)));
+}
+
+function matchDomainSync(input, candidates, options = {}) {
+  const results = [];
+  for (const candidate of candidates || []) {
+    const info = typeof candidate === 'string' || candidate instanceof Uint8Array || isAsset(candidate)
+      ? inspectKDNASync(candidate, { ...options, verify: false })
+      : candidate;
+    const match = scoreMatch(input, info);
+    if (match.score > 0) results.push({ ...info, score: match.score, matched: match.matched });
+  }
+  return results.sort((a, b) => b.score - a.score || String(a.name).localeCompare(String(b.name)));
+}
+
+async function composeKDNA(inputs, options = {}) {
+  const loaded = [];
+  for (const input of inputs || []) {
+    const profile = await loadKDNA(input, { ...options, profile: options.profile || 'compact', context: false });
+    if (profile.domain) {
+      loaded.push({
+        id: profile.manifest.name || profile.domain.core?.meta?.domain,
+        name: profile.manifest.name || profile.domain.core?.meta?.domain,
+        manifest: profile.manifest,
+        ...profile.domain,
+      });
+    }
+  }
+  const { selected, excluded } = classifySignalsAcrossDomains(options.input || '', loaded);
+  const selectedIds = new Set(selected.map((d) => d.id));
+  const activeDomains = options.input ? loaded.filter((d) => selectedIds.has(d.id)) : loaded;
+  const conflicts = detectDomainConflicts(activeDomains);
+  const { context, attributionMap } = composeContextWithAttribution(activeDomains, options);
+  return {
+    domains: loaded,
+    activeDomains,
+    selected,
+    excluded,
+    conflicts,
+    context,
+    attributionMap,
+    trace: generateClusterTrace({
+      input: options.input || '',
+      loadedDomains: loaded,
+      activeDomains,
+      conflicts,
+    }),
+  };
+}
+
+module.exports = {
+  openKDNA,
+  openKDNASync,
+  inspectKDNA,
+  inspectKDNASync,
+  loadKDNA,
+  loadKDNASync,
+  validateKDNA,
+  validateKDNASync,
+  renderForAgent,
+  renderForAgentSync,
+  verifyAsset,
+  verifyAssetSync,
+  verifyDigest,
+  verifyDigestSync,
+  verifySignature,
+  verifySignatureSync,
+  matchDomain,
+  matchDomainSync,
+  composeKDNA,
+};