@aikdna/kdna-core 0.21.0 → 0.22.0

package/src/container/index.js

@@ -18,8 +18,9 @@
  *   - mimetype must be the first entry in a .kdna container
  *   - mimetype must be STORED (compression method 0) in a .kdna container
  *   - the source directory must contain mimetype, kdna.json, payload.kdnab
- *   - checksums.json and attachments/ are optional
- *   - asset signatures are outside the current Preview contract
+ *   - checksums.json, attachments/, and signature.kdsig are optional
+ *   - signature.kdsig is the RFC-0021 M1 `kdsig.ed25519` bundle; when present
+ *     it must verify fail-closed against the canonical content digest
  *   - lineage must be a single object (not an array)
  *   - pack output is reproducible within one pinned toolchain/compressor;
  *     DEFLATE bytes may differ across compressors, zlib versions, or systems
@@ -91,7 +92,7 @@ const { readAsset } = (() => {
 
 const MIMETYPE = 'application/vnd.kdna.asset';
 const REQUIRED_DIR_ENTRIES = ['mimetype', 'kdna.json', 'payload.kdnab'];
-const OPTIONAL_DIR_ENTRIES = ['checksums.json', 'attachments'];
+const OPTIONAL_DIR_ENTRIES = ['checksums.json', 'attachments', 'signature.kdsig'];
 const ALLOWED_TOP_LEVEL_ENTRIES = new Set([
   ...REQUIRED_DIR_ENTRIES,
   ...OPTIONAL_DIR_ENTRIES,
@@ -587,6 +588,13 @@ function readLayout(absPath) {
       if (fs.existsSync(full)) {
         if (fs.statSync(full).isFile()) {
           map[f] = fs.readFileSync(full);
+        } else if (f === 'attachments') {
+          // Attachment files join the entry map under their relative names so
+          // digest and signature operations see the same entry set as the
+          // packaged container.
+          for (const entry of listSourceDir(full)) {
+            map[`attachments/${entry.rel}`] = fs.readFileSync(entry.full);
+          }
         } else {
           // Optional subdirectories are recorded without becoming payloads.
           map[f] = null;
@@ -606,7 +614,8 @@ function readLayout(absPath) {
         e.name === 'mimetype' ||
         e.name === 'kdna.json' ||
         e.name === 'payload.kdnab' ||
-        e.name === 'checksums.json'
+        e.name === 'checksums.json' ||
+        e.name === 'signature.kdsig'
       ) {
         map[e.name] = e.data;
       }
@@ -663,7 +672,8 @@ function readLayoutBytes(input) {
       entry.name === 'mimetype' ||
       entry.name === 'kdna.json' ||
       entry.name === 'payload.kdnab' ||
-      entry.name === 'checksums.json'
+      entry.name === 'checksums.json' ||
+      entry.name === 'signature.kdsig'
     ) {
       map[entry.name] = entry.data;
     }
@@ -811,6 +821,7 @@ function buildInspectOutput(container) {
     load_contract_default_profile: m.load_contract ? m.load_contract.default_profile : null,
   };
   if (container.map['checksums.json']) out.checksums_present = true;
+  if (container.map['signature.kdsig']) out.signature_present = true;
   return out;
 }
 
@@ -827,6 +838,9 @@ function runValidate(layout) {
     schema_valid: true,
     payload_valid: true,
     checksums_valid: true,
+    signature_valid: true,
+    signature_state: 'absent',
+    signature_evidence: null,
     load_contract_valid: true,
     ...assessLoaderCompatibility(layout.manifest),
   };
@@ -981,6 +995,26 @@ function runValidate(layout) {
     }
   }
 
+  // signature gate — RFC-0021 M1 (`kdsig.ed25519`). An absent signature is
+  // not an error; a present signature must verify fail-closed.
+  if (layout.map['signature.kdsig'] !== undefined) {
+    try {
+      const signature = require('../signature');
+      const { contentDigestFromEntryBuffers } = require('../asset-reader');
+      const contentDigest = contentDigestFromEntryBuffers(fullEntryBufferMap(layout));
+      const evidence = signature.verifySignatureBundle(
+        layout.map['signature.kdsig'],
+        contentDigest,
+      );
+      result.signature_state = 'verified';
+      result.signature_evidence = evidence;
+    } catch (e) {
+      result.signature_valid = false;
+      result.signature_state = 'invalid';
+      problems.push(`signature: ${e.message}`);
+    }
+  }
+
   // load_contract gate — only if manifest references a load_contract block
   if (layout.manifest.load_contract) {
     const lc = layout.manifest.load_contract;
@@ -1098,12 +1132,39 @@ function verifyDigests(checksums, map, problems, result) {
   return stillValid;
 }
 
+/**
+ * Collect every file entry of a layout as name → Buffer, so digest and
+ * signature operations always cover the full entry set (including
+ * attachments), regardless of which entries layout.map parses.
+ */
+function fullEntryBufferMap(layout) {
+  const buffers = {};
+  if (Array.isArray(layout.entries)) {
+    for (const entry of layout.entries) {
+      // Entries are either parsed ZIP entry objects ({ name, data }) or plain
+      // entry names from the unified container model; both resolve through
+      // layout.map.
+      const name = typeof entry === 'string' ? entry : entry.name;
+      const data = typeof entry === 'string' ? layout.map[entry] : entry.data;
+      if (data === undefined || data === null) continue;
+      buffers[name] = data;
+    }
+    return buffers;
+  }
+  for (const [name, data] of Object.entries(layout.map)) {
+    if (data === null || data === undefined) continue;
+    buffers[name] = data;
+  }
+  return buffers;
+}
+
 function finalizeValidate(result, problems) {
   result.overall_valid =
     result.format_valid &&
     result.schema_valid &&
     result.payload_valid &&
     result.checksums_valid &&
+    result.signature_valid &&
     result.load_contract_valid;
   result.problems = problems;
   return result;
@@ -1260,6 +1321,108 @@ function pack(sourceDir, outputPath) {
   return { outputPath, entries: order };
 }
 
+/**
+ * Deterministically pack an in-memory entry map into .kdna container bytes.
+ * mimetype is forced first and STORED; remaining entries are ordered by UTF-8
+ * path bytes and DEFLATE-compressed; timestamps are pinned to the DOS epoch.
+ */
+function packEntryMap(map) {
+  for (const f of REQUIRED_DIR_ENTRIES) {
+    if (!map[f]) throw new Error(`cannot pack: missing required entry ${f}`);
+  }
+  const mime = Buffer.isBuffer(map.mimetype) ? map.mimetype.toString('utf8') : String(map.mimetype);
+  if (mime !== MIMETYPE) {
+    throw new Error(`cannot pack: mimetype is "${mime}", expected "${MIMETYPE}"`);
+  }
+  const names = Object.keys(map).filter((name) => name !== 'mimetype');
+  names.sort((a, b) => Buffer.compare(Buffer.from(a, 'utf8'), Buffer.from(b, 'utf8')));
+  const order = ['mimetype', ...names];
+
+  const localChunks = [];
+  const centralChunks = [];
+  let offset = 0;
+  for (const rel of order) {
+    const data = rel === 'mimetype' ? Buffer.from(MIMETYPE, 'utf8') : Buffer.from(map[rel]);
+    const nameBytes = Buffer.from(rel, 'utf8');
+    const method = rel === 'mimetype' ? 0 : 8;
+    const built = buildLocalHeader(nameBytes, data, method);
+    localChunks.push(built.local, built.compressed);
+    centralChunks.push(
+      buildCentral(
+        {
+          method,
+          crc: built.crc,
+          time: built.time,
+          date: built.date,
+          compressed: built.compressed,
+          dataLength: built.dataLength,
+          offset,
+        },
+        nameBytes,
+      ),
+    );
+    offset += built.local.length + built.compressed.length;
+  }
+
+  const centralOffset = offset;
+  let centralSize = 0;
+  for (const c of centralChunks) centralSize += c.length;
+  const eocd = Buffer.alloc(22);
+  eocd.writeUInt32LE(0x06054b50, 0);
+  eocd.writeUInt16LE(0, 4);
+  eocd.writeUInt16LE(0, 6);
+  eocd.writeUInt16LE(order.length, 8);
+  eocd.writeUInt16LE(order.length, 10);
+  eocd.writeUInt32LE(centralSize, 12);
+  eocd.writeUInt32LE(centralOffset, 16);
+  eocd.writeUInt16LE(0, 20);
+
+  return Buffer.concat([...localChunks, ...centralChunks, eocd]);
+}
+
+/**
+ * Sign a packaged .kdna container per RFC-0021 M1 (`kdsig.ed25519`).
+ *
+ * The container must pass every validation gate after any pre-existing
+ * signature entry is removed; signing never certifies a broken asset. The
+ * returned bytes carry a fresh `signature.kdsig` bundle whose Ed25519
+ * signature covers the canonical content digest. Fail-closed throughout.
+ */
+function signContainerBytes(input, privateKeySeedHex, _opts = {}) {
+  const signature = require('../signature');
+  const { contentDigestFromEntryBuffers } = require('../asset-reader');
+
+  const bytes = Buffer.isBuffer(input) ? input : Buffer.from(input);
+  const layout = readLayoutBytes(bytes);
+
+  // Rebuild the full entry map (including attachments) from the parsed
+  // ZIP entries; layout.map only carries the well-known protocol entries.
+  const unsignedMap = {};
+  for (const entry of layout.entries) {
+    if (entry.name === 'signature.kdsig') continue;
+    unsignedMap[entry.name] = entry.data;
+  }
+  const validation = runValidate({ ...layout, map: unsignedMap });
+  if (!validation.overall_valid) {
+    const error = new Error(
+      `cannot sign: container does not pass validation (${validation.problems.join('; ')})`,
+    );
+    error.code = 'KDNA_SIGNATURE_INPUT_INVALID';
+    throw error;
+  }
+
+  const contentDigest = contentDigestFromEntryBuffers(unsignedMap);
+  const bundle = signature.signContentDigest(contentDigest, privateKeySeedHex);
+  const bundleBytes = signature.serializeSignatureBundle(bundle);
+  const signedMap = { ...unsignedMap, [signature.SIGNATURE_ENTRY_NAME]: bundleBytes };
+  return {
+    containerBytes: packEntryMap(signedMap),
+    bundle,
+    bundleBytes,
+    content_digest: contentDigest,
+  };
+}
+
 // ─── unpack ────────────────────────────────────────────────────────────
 
 /**
@@ -1340,6 +1503,12 @@ function buildLoadPlanIssue(code, severity, message) {
 
 function validationProblemCode(problem) {
   if (/checksums?:/i.test(problem)) return 'KDNA_INTEGRITY_DIGEST_FAILED';
+  if (/signature bundle profile_version .* is not supported/i.test(problem)) {
+    return 'KDNA_SIGNATURE_VERSION_UNSUPPORTED';
+  }
+  if (/signature bundle (profile|algorithm) .* is not supported/i.test(problem)) {
+    return 'KDNA_SIGNATURE_PROFILE_UNSUPPORTED';
+  }
   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';
@@ -1413,9 +1582,11 @@ function baseLoadPlan(inputPath, layout, validation, opts = {}) {
       schema_valid: validation.schema_valid,
       payload_valid: validation.payload_valid,
       checksums_valid: validation.checksums_valid,
+      signature_valid: validation.signature_valid,
       load_contract_valid: validation.load_contract_valid,
       overall_valid: validation.overall_valid,
     },
+    signature_state: validation.signature_state,
     issues: [],
     source: {
       kind: layout.kind,
@@ -1481,7 +1652,8 @@ function planLoad(inputPath, opts = {}) {
         access: null, access_alias: null, entitlement_profile: null,
         state: 'invalid', required_action: 'block', can_load_now: false, projection_policy: 'none',
         input_fingerprint: null,
-        checks: { format_valid: false, schema_valid: false, payload_valid: false, checksums_valid: false, load_contract_valid: false, overall_valid: false },
+        checks: { format_valid: false, schema_valid: false, payload_valid: false, checksums_valid: false, signature_valid: false, load_contract_valid: false, overall_valid: false },
+        signature_state: 'absent',
         issues: [buildLoadPlanIssue('KDNA_FORMAT_INVALID', 'blocking', e.message)],
         source: inputSource(inputPath, 'memory'),
       });
@@ -1505,7 +1677,8 @@ function planLoad(inputPath, opts = {}) {
           access: null, access_alias: null, entitlement_profile: null,
           state: 'invalid', required_action: 'block', can_load_now: false, projection_policy: 'none',
           input_fingerprint: null,
-          checks: { format_valid: false, schema_valid: false, payload_valid: false, checksums_valid: false, load_contract_valid: false, overall_valid: false },
+          checks: { format_valid: false, schema_valid: false, payload_valid: false, checksums_valid: false, signature_valid: false, load_contract_valid: false, overall_valid: false },
+          signature_state: 'absent',
           issues: [buildLoadPlanIssue(
             e.code === 'KDNA_FORMAT_UNKNOWN' ? 'KDNA_FORMAT_UNKNOWN' : 'KDNA_FORMAT_INVALID',
             'blocking', e.message,
@@ -1526,7 +1699,8 @@ function planLoad(inputPath, opts = {}) {
         access: null, access_alias: null, entitlement_profile: null,
         state: 'invalid', required_action: 'block', can_load_now: false, projection_policy: 'none',
         input_fingerprint: null,
-        checks: { format_valid: false, schema_valid: false, payload_valid: false, checksums_valid: false, load_contract_valid: false, overall_valid: false },
+        checks: { format_valid: false, schema_valid: false, payload_valid: false, checksums_valid: false, signature_valid: false, load_contract_valid: false, overall_valid: false },
+        signature_state: 'absent',
         issues: [buildLoadPlanIssue('KDNA_FORMAT_INVALID', 'blocking', e.message)],
         source: inputSource(inputPath, null),
       });
@@ -1979,6 +2153,8 @@ module.exports = {
   isKdnaSourceDir,
   detectContainerFormat,
   readLayout: readLayout,
+  readLayoutBytes,
+  fullEntryBufferMap,
   inspect,
   validate,
   planLoad,
@@ -1986,6 +2162,8 @@ module.exports = {
   buildChecksums: buildChecksums,
   computeRuntimeEntrySetDigest,
   pack,
+  packEntryMap,
+  signContainerBytes,
   unpack,
   load: loadAsset,
   loadAsset: loadAsset,
@@ -2116,7 +2294,8 @@ function loadAuthorized(inputPath, opts = {}) {
     extendsChain: plan.extends_chain || [],
     _validation: {
       schema_valid: plan.checks && plan.checks.overall_valid === true,
-      signature_valid: plan.signature_valid === true,
+      signature_valid: plan.checks && plan.checks.signature_valid === true,
+      signature_state: plan.signature_state,
     },
     _runtimeAssetBytes: inputSnapshot,
     _runtimeInputKind: inputKind,
@@ -2158,9 +2337,11 @@ function packagedAssetRequiredPlan(inputPath) {
       schema_valid: false,
       payload_valid: false,
       checksums_valid: false,
+      signature_valid: false,
       load_contract_valid: false,
       overall_valid: false,
     },
+    signature_state: 'absent',
     issues: [buildLoadPlanIssue(
       'KDNA_ASSET_FILE_REQUIRED',
       'blocking',
@@ -2259,7 +2440,8 @@ function loadRemoteRuntimeAssetForServer(inputPath) {
     extendsChain: [],
     _validation: {
       schema_valid: plan.checks.overall_valid === true,
-      signature_valid: plan.signature_valid === true,
+      signature_valid: plan.checks.signature_valid === true,
+      signature_state: plan.signature_state,
     },
     _runtimeAssetBytes: inputSnapshot,
     _runtimeInputKind: inputKind,
@@ -2319,6 +2501,27 @@ function hasStandardJudgmentRoleContent(role) {
   );
 }
 
+function projectMinimalAxiom(axiom) {
+  const normalized = normalizeCompactAxiom(axiom);
+  if (!normalized) return null;
+  return {
+    type: 'axiom_applicability',
+    id: normalized.id || null,
+    one_sentence: normalized.one_sentence || null,
+    does_not_apply_when: normalized.does_not_apply_when || [],
+    failure_risk: normalized.failure_risk || null,
+  };
+}
+
+function hasMinimalPromptContent(content) {
+  if (!content) return false;
+  return Boolean(
+    content.highest_question ||
+      (Array.isArray(content.axioms) && content.axioms.length > 0) ||
+      (Array.isArray(content.boundaries) && content.boundaries.length > 0)
+  );
+}
+
 function hasCompactPromptContent(content) {
   if (!content) return false;
   return Boolean(
@@ -2566,6 +2769,17 @@ function loadAssetUnsafe(inputPath, opts = {}) {
       || (payload.reasoning && ((payload.reasoning.self_check && payload.reasoning.self_check.length > 0) || (payload.reasoning.failure_modes && payload.reasoning.failure_modes.length > 0)));
     profiles.push('index');
     if (hasJudgment) profiles.push('compact');
+    // RFC-0020: minimal availability follows the manifest declaration, not
+    // payload inference. An asset that declares minimal in load_contract
+    // (and carries core judgment) may be projected minimally.
+    if (
+      hasJudgment &&
+      m.load_contract &&
+      m.load_contract.profiles &&
+      m.load_contract.profiles.minimal
+    ) {
+      profiles.push('minimal');
+    }
     if (payload.scenarios && payload.scenarios.length > 0) profiles.push('scenario');
     profiles.push('full');
     return profiles;
@@ -2657,6 +2871,34 @@ function loadAssetUnsafe(inputPath, opts = {}) {
     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;
     }
+  } else if (profile === 'minimal') {
+    const core = payload.core || {};
+    // RFC-0020: minimal availability follows the manifest declaration. If the
+    // asset does not declare minimal in load_contract, fail closed with an
+    // empty projection rather than silently serving a projection the asset
+    // did not opt into.
+    if (!result.profile_available) {
+      result.content = {};
+      result.projection_report = buildCompactProjectionReport(payload);
+    } else {
+      const normalizeList = (items) => (items || []).map((item) => {
+        if (typeof item === 'string') return { type: 'text', text: item };
+        if (item && typeof item === 'object') return item;
+        return null;
+      }).filter(Boolean);
+      // RFC-0020: minimal projects the core judgment surface a small model needs:
+      // highest_question + boundary-friendly axioms + full boundaries. It is a
+      // strict subset of compact (deterministic reduction, no inference).
+      result.content = {
+        highest_question: core.highest_question || null,
+        axioms: (core.axioms || []).map(projectMinimalAxiom).filter(Boolean),
+        boundaries: normalizeList(core.boundaries),
+      };
+      result.projection_report = buildCompactProjectionReport(payload);
+      if (m.load_contract && m.load_contract.profiles && m.load_contract.profiles.minimal && m.load_contract.profiles.minimal.max_tokens_hint) {
+        result.max_tokens_hint = m.load_contract.profiles.minimal.max_tokens_hint;
+      }
+    }
   } else if (profile === 'scenario') {
     result.content = { scenarios: payload.scenarios || [] };
   } else if (profile === 'full') {
@@ -2750,15 +2992,23 @@ function loadAssetUnsafe(inputPath, opts = {}) {
     const c = result.content;
     const compactHasNoPromptContent =
       result.profile === 'compact' && !hasCompactPromptContent(c);
+    const minimalHasNoPromptContent =
+      result.profile === 'minimal' && !hasMinimalPromptContent(c);
     const legacyProfileHasNoPromptContent =
       result.profile !== 'compact' &&
+      result.profile !== 'minimal' &&
       c &&
       c.scenarios &&
       c.scenarios.length === 0 &&
       !c.highest_question &&
       !(c.axioms && c.axioms.length) &&
       !(c.boundaries && c.boundaries.length);
-    if (!c || compactHasNoPromptContent || legacyProfileHasNoPromptContent) {
+    if (
+      !c ||
+      compactHasNoPromptContent ||
+      minimalHasNoPromptContent ||
+      legacyProfileHasNoPromptContent
+    ) {
       return {
         status: result.status,
         profile: result.profile,
@@ -2850,6 +3100,23 @@ function wrapAsCapsule(result, layout, profile, opts) {
   return result;
 }
 
+function buildSignatureEvidence(layout) {
+  if (!layout || !layout.map || layout.map['signature.kdsig'] === undefined) {
+    return { state: 'absent' };
+  }
+  const signature = require('../signature');
+  const { contentDigestFromEntryBuffers } = require('../asset-reader');
+  const contentDigest = contentDigestFromEntryBuffers(fullEntryBufferMap(layout));
+  const evidence = signature.verifySignatureBundle(layout.map['signature.kdsig'], contentDigest);
+  return {
+    state: 'verified',
+    profile: evidence.profile,
+    profile_version: evidence.profile_version,
+    key_fingerprint: evidence.key_fingerprint,
+    content_digest: evidence.content_digest,
+  };
+}
+
 function buildRuntimeCapsuleProjection(loadResult, layout, profile, opts = {}) {
   const m = layout.manifest;
   const val = opts._validation || {};
@@ -2861,7 +3128,7 @@ function buildRuntimeCapsuleProjection(loadResult, layout, profile, opts = {}) {
     projection: loadResult,
     manifest: m,
     digests,
-    signature: { state: 'absent' },
+    signature: buildSignatureEvidence(layout),
     inputKind: opts._runtimeInputKind,
     loadedAt: opts.loadedAt,
     schemaValid: val.schema_valid === true,

package/src/index.js

@@ -15,9 +15,11 @@ const runtimeApi = require('./runtime-api');
 const runtimeCapsule = require('./runtime-capsule');
 const runtimeContract = require('./runtime-contract');
 const loaderCompatibility = require('./loader-compatibility');
+const assetSignature = require('./signature');
 
 module.exports = {
   ...publicApi,
+  ...assetSignature,
   ...loader,
   ...validate,
   ...render,

package/src/index.mjs

@@ -17,10 +17,14 @@ export {
   isKdnaSourceDir,
   detectContainerFormat,
   readLayout,
+  readLayoutBytes,
+  fullEntryBufferMap,
   inspect,
   validate,
   buildChecksums,
   pack,
+  packEntryMap,
+  signContainerBytes,
   unpack,
   FORBIDDEN_OUTPUT_TERMS,
   parseSemver,
@@ -80,8 +84,25 @@ export const verifyDigest = publicApi.verifyDigest;
 export const verifyDigestSync = publicApi.verifyDigestSync;
 export const matchDomain = publicApi.matchDomain;
 export const matchDomainSync = publicApi.matchDomainSync;
+export const signKDNA = publicApi.signKDNA;
+export const signKDNASync = publicApi.signKDNASync;
+export const verifyKDNASignature = publicApi.verifyKDNASignature;
+export const verifyKDNASignatureSync = publicApi.verifyKDNASignatureSync;
 export const composeKDNA = publicApi.composeKDNA;
 
+import assetSignature from './signature.js';
+export const KDSIG_PROFILE = assetSignature.KDSIG_PROFILE;
+export const KDSIG_PROFILE_VERSION = assetSignature.KDSIG_PROFILE_VERSION;
+export const KDSIG_ALGORITHM = assetSignature.KDSIG_ALGORITHM;
+export const SIGNATURE_ENTRY_NAME = assetSignature.SIGNATURE_ENTRY_NAME;
+export const buildSigningPayload = assetSignature.buildSigningPayload;
+export const generateSigningKeyPair = assetSignature.generateSigningKeyPair;
+export const keyFingerprint = assetSignature.keyFingerprint;
+export const parseSignatureBundle = assetSignature.parseSignatureBundle;
+export const serializeSignatureBundle = assetSignature.serializeSignatureBundle;
+export const signContentDigest = assetSignature.signContentDigest;
+export const verifySignatureBundle = assetSignature.verifySignatureBundle;
+
 export const DIGEST_PROFILE = runtimeCapsule.DIGEST_PROFILE;
 export const DIGEST_PROFILE_VERSION = runtimeCapsule.DIGEST_PROFILE_VERSION;
 export const CAPSULE_DIGEST_PROFILE = runtimeCapsule.CAPSULE_DIGEST_PROFILE;
@@ -121,6 +142,7 @@ export const validateJudgmentTrace = runtimeContract.validateJudgmentTrace;
 
 export const STANDARD_ENTRIES = assetReader.STANDARD_ENTRIES;
 export const createKdnaAssetReader = assetReader.createKdnaAssetReader;
+export const contentDigestFromEntryBuffers = assetReader.contentDigestFromEntryBuffers;
 
 export const {
   LICENSED_ENTRY_PROFILE,

package/src/public-api.js

@@ -8,9 +8,10 @@
  */
 
 const fs = require('fs');
-const { createKdnaAssetReader } = require('./asset-reader');
+const { createKdnaAssetReader, contentDigestFromEntryBuffers } = require('./asset-reader');
 const container = require('./container');
 const runtimeApi = require('./runtime-api');
+const signature = require('./signature');
 
 function readerFrom(options = {}) {
   return options.reader || createKdnaAssetReader();
@@ -176,6 +177,55 @@ function matchDomainSync(input, candidates, options = {}) {
   return results.sort((a, b) => b.score - a.score || String(a.asset_id).localeCompare(String(b.asset_id)));
 }
 
+/**
+ * Sign a packaged .kdna asset per RFC-0021 M1 (`kdsig.ed25519`). Returns the
+ * signed container bytes, the signature bundle, and the signed content
+ * digest. `privateKey` is the raw 32-byte Ed25519 seed as 64 lowercase hex
+ * characters. When `options.outputPath` is set the signed container is also
+ * written to that path.
+ */
+function signKDNASync(input, privateKey, options = {}) {
+  const result = container.signContainerBytes(canonicalBytes(input), privateKey, options);
+  if (typeof options.outputPath === 'string' && options.outputPath.length > 0) {
+    fs.writeFileSync(options.outputPath, result.containerBytes);
+  }
+  return result;
+}
+
+async function signKDNA(input, privateKey, options = {}) {
+  return signKDNASync(input, privateKey, options);
+}
+
+/**
+ * Verify the RFC-0021 M1 (`kdsig.ed25519`) signature of a packaged .kdna
+ * asset offline. Fail-closed: any malformed, unsupported, or unverifiable
+ * bundle throws. Returns `{ state: 'absent' }` for unsigned assets unless
+ * `options.required` is true (then absence also throws), and the verified
+ * evidence otherwise. `options.expectedPublicKey` pins the signer key.
+ */
+function verifyKDNASignatureSync(input, options = {}) {
+  const layout = container.readLayoutBytes(canonicalBytes(input));
+  const bundleBytes = layout.map[signature.SIGNATURE_ENTRY_NAME];
+  if (bundleBytes === undefined) {
+    if (options.required === true) {
+      const error = new Error(
+        `required asset signature is absent: missing entry ${signature.SIGNATURE_ENTRY_NAME}`,
+      );
+      error.code = 'KDNA_SIGNATURE_ABSENT';
+      throw error;
+    }
+    return { state: 'absent' };
+  }
+  const contentDigest = contentDigestFromEntryBuffers(container.fullEntryBufferMap(layout));
+  return signature.verifySignatureBundle(bundleBytes, contentDigest, {
+    expectedPublicKey: options.expectedPublicKey,
+  });
+}
+
+async function verifyKDNASignature(input, options = {}) {
+  return verifyKDNASignatureSync(input, options);
+}
+
 async function composeKDNA(inputs, options = {}) {
   void inputs;
   void options;
@@ -203,5 +253,9 @@ module.exports = {
   verifyDigestSync,
   matchDomain,
   matchDomainSync,
+  signKDNA,
+  signKDNASync,
+  verifyKDNASignature,
+  verifyKDNASignatureSync,
   composeKDNA,
 };