@aikdna/kdna-core 0.20.0 → 0.22.0

package/src/crypto-profile.js

@@ -278,6 +278,18 @@ function ensureArgon2id() {
   }
 }
 
+const MAX_ARGON2_MEMORY_KIB = 262144; // 256 MiB
+const MAX_ARGON2_ITERATIONS = 16;
+const MAX_ARGON2_PARALLELISM = 8;
+
+function boundedArgon2Param(value, name, max) {
+  if (value === undefined) return undefined;
+  if (!Number.isSafeInteger(value) || value < 1 || value > max) {
+    throw new Error(`unsupported Argon2id ${name}: must be an integer between 1 and ${max}`);
+  }
+  return value;
+}
+
 function derivePasswordKey(password, params = {}) {
   ensureArgon2id();
   const {
@@ -287,12 +299,15 @@ function derivePasswordKey(password, params = {}) {
     parallelism = 4,
   } = params;
   if (!salt) throw new Error('salt is required for Argon2id');
+  const boundedMemory = boundedArgon2Param(memory_kib, 'memory_kib', MAX_ARGON2_MEMORY_KIB);
+  const boundedIterations = boundedArgon2Param(iterations, 'iterations', MAX_ARGON2_ITERATIONS);
+  const boundedParallelism = boundedArgon2Param(parallelism, 'parallelism', MAX_ARGON2_PARALLELISM);
   const saltBuf = decodeBase64(salt, 'salt');
   const passwordBuf = toBuffer(password, 'password');
   const key = argon2id(passwordBuf, saltBuf, {
-    t: iterations,
-    m: memory_kib,
-    p: parallelism,
+    t: boundedIterations,
+    m: boundedMemory,
+    p: boundedParallelism,
     dkLen: 32,
   });
   return Buffer.from(key);

package/src/external-key-grant.js

@@ -7,11 +7,12 @@
  */
 
 const crypto = require('node:crypto');
-const path = require('node:path');
 const JsonSchema2020 = require('ajv/dist/2020');
 const addFormats = require('ajv-formats');
 const cbor = require('cbor-x');
 const { hkdfSha256, aesWrap, aesUnwrap } = require('./crypto-profile');
+const externalEnvelopeSchema = require('../schema/external-grant-envelope.schema.json');
+const externalKeyGrantSchema = require('../schema/external-key-grant.schema.json');
 
 const EXTERNAL_ENVELOPE_PROFILE = 'kdna.envelope.external-grant';
 const EXTERNAL_GRANT_PROFILE = 'kdna.grant.external-key';
@@ -21,15 +22,10 @@ const EXTERNAL_GRANT_CONTRACT_VERSION = '0.1.0';
 const ENVELOPE_ALG = 'A256GCM';
 const GRANT_WRAP_ALG = 'X25519-HKDF-SHA256+A256KW';
 
-const schemaRoot = path.join(__dirname, '..', 'schema');
 const ajv = new JsonSchema2020({ allErrors: true, strict: true });
 addFormats(ajv);
-const validateEnvelopeSchema = ajv.compile(
-  require(path.join(schemaRoot, 'external-grant-envelope.schema.json')),
-);
-const validateGrantSchema = ajv.compile(
-  require(path.join(schemaRoot, 'external-key-grant.schema.json')),
-);
+const validateEnvelopeSchema = ajv.compile(externalEnvelopeSchema);
+const validateGrantSchema = ajv.compile(externalKeyGrantSchema);
 
 const verifiedEntitlements = new WeakSet();
 

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,
@@ -78,12 +82,27 @@ export const verifyAsset = publicApi.verifyAsset;
 export const verifyAssetSync = publicApi.verifyAssetSync;
 export const verifyDigest = publicApi.verifyDigest;
 export const verifyDigestSync = publicApi.verifyDigestSync;
-export const verifySignature = publicApi.verifySignature;
-export const verifySignatureSync = publicApi.verifySignatureSync;
 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;
@@ -123,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();
@@ -63,7 +64,6 @@ async function inspectKDNA(input, options = {}) {
     entries,
     asset_digest: asset.asset_digest,
     content_digest: contentDigest,
-    signature_valid: verification ? verification.signature_valid : null,
     ok: verification ? verification.ok : null,
     errors: verification ? verification.errors : [],
     warnings: verification ? verification.warnings : [],
@@ -84,7 +84,6 @@ function inspectKDNASync(input, options = {}) {
     entries,
     asset_digest: asset.asset_digest,
     content_digest: contentDigest,
-    signature_valid: verification ? verification.signature_valid : null,
     ok: verification ? verification.ok : null,
     errors: verification ? verification.errors : [],
     warnings: verification ? verification.warnings : [],
@@ -138,14 +137,6 @@ 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 = [
@@ -186,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;
@@ -211,9 +251,11 @@ module.exports = {
   verifyAssetSync,
   verifyDigest,
   verifyDigestSync,
-  verifySignature,
-  verifySignatureSync,
   matchDomain,
   matchDomainSync,
+  signKDNA,
+  signKDNASync,
+  verifyKDNASignature,
+  verifyKDNASignatureSync,
   composeKDNA,
 };

package/src/runtime-capsule.js

@@ -8,6 +8,10 @@ const addFormats = require('ajv-formats');
 
 const { createKdnaAssetReader } = require('./asset-reader');
 const container = require('./container');
+const {
+  KDSIG_PROFILE,
+  KDSIG_PROFILE_VERSION,
+} = require('./signature');
 const digestEvidenceSchema = require('../schema/digest-evidence.schema.json');
 const runtimeCapsuleSchema = require('../schema/runtime-capsule.schema.json');
 
@@ -433,6 +437,82 @@ function assertSuccessfulDigestEvidence(digests) {
   }
 }
 
+const SIGNATURE_EVIDENCE_FIELDS = Object.freeze({
+  absent: ['state'],
+  verified: ['state', 'profile', 'profile_version', 'key_fingerprint', 'content_digest'],
+});
+
+/**
+ * Normalize Runtime Capsule signature evidence (RFC-0021 M1). Unsigned assets
+ * report `{ state: 'absent' }`; signed assets report the verified kdsig.ed25519
+ * evidence. Any other shape fails closed — signatures never downgrade to
+ * "absent" and unknown profiles are never collapsed into known ones.
+ */
+function normalizeSignatureEvidence(signature) {
+  if (signature === undefined) return { state: 'absent' };
+  if (!signature || typeof signature !== 'object' || Array.isArray(signature)) {
+    fail(
+      'KDNA_RUNTIME_CAPSULE_BUILD_INVALID',
+      'Runtime Capsule signature evidence must be an object.',
+    );
+  }
+  if (signature.state === 'absent') {
+    const extra = Object.keys(signature).filter((key) => key !== 'state');
+    if (extra.length) {
+      fail(
+        'KDNA_RUNTIME_CAPSULE_BUILD_INVALID',
+        'Absent signature evidence must not carry extra fields.',
+      );
+    }
+    return { state: 'absent' };
+  }
+  if (signature.state === 'verified') {
+    const keys = Object.keys(signature).sort();
+    const expected = [...SIGNATURE_EVIDENCE_FIELDS.verified].sort();
+    if (keys.join(',') !== expected.join(',')) {
+      fail(
+        'KDNA_RUNTIME_CAPSULE_BUILD_INVALID',
+        `Verified signature evidence must carry exactly: ${SIGNATURE_EVIDENCE_FIELDS.verified.join(', ')}.`,
+      );
+    }
+    if (signature.profile !== KDSIG_PROFILE) {
+      fail(
+        'KDNA_ASSET_SIGNATURE_UNSUPPORTED',
+        `Signature profile ${JSON.stringify(signature.profile)} is not supported (supported: ${KDSIG_PROFILE}).`,
+      );
+    }
+    if (signature.profile_version !== KDSIG_PROFILE_VERSION) {
+      fail(
+        'KDNA_ASSET_SIGNATURE_UNSUPPORTED',
+        `Signature profile_version ${JSON.stringify(signature.profile_version)} is not supported (supported: ${KDSIG_PROFILE_VERSION}).`,
+      );
+    }
+    if (!SHA256_RE.test(signature.key_fingerprint || '')) {
+      fail(
+        'KDNA_RUNTIME_CAPSULE_BUILD_INVALID',
+        'Verified signature evidence requires a sha256 key_fingerprint.',
+      );
+    }
+    if (!SHA256_RE.test(signature.content_digest || '')) {
+      fail(
+        'KDNA_RUNTIME_CAPSULE_BUILD_INVALID',
+        'Verified signature evidence requires a sha256 content_digest.',
+      );
+    }
+    return {
+      state: 'verified',
+      profile: signature.profile,
+      profile_version: signature.profile_version,
+      key_fingerprint: signature.key_fingerprint,
+      content_digest: signature.content_digest,
+    };
+  }
+  fail(
+    'KDNA_ASSET_SIGNATURE_UNSUPPORTED',
+    `Signature state ${JSON.stringify(signature.state)} is not supported (supported: absent, verified).`,
+  );
+}
+
 function normalizeRuntimeAccess(access) {
   return access === undefined ? 'public' : access;
 }
@@ -475,7 +555,7 @@ function buildRuntimeCapsule({
   if (!['public', 'licensed', 'remote'].includes(runtimeAccess)) {
     fail('KDNA_RUNTIME_CAPSULE_BUILD_INVALID', `Unsupported Runtime access: ${runtimeAccess}.`);
   }
-  const signatureEvidence = signature || { state: 'absent' };
+  const signatureEvidence = normalizeSignatureEvidence(signature);
 
   const capsule = {
     type: 'kdna.runtime-capsule',
@@ -502,6 +582,9 @@ function buildRuntimeCapsule({
       profile: projection.profile,
     },
   };
+  if (projection.projection_report !== undefined) {
+    capsule.trace.projection_report = globalThis.structuredClone(projection.projection_report);
+  }
   assertRuntimeCapsuleSuccess(capsule, 'KDNA_RUNTIME_CAPSULE_BUILD_INVALID');
   return capsule;
 }

package/src/signature.js

@@ -0,0 +1,320 @@
+/**
+ * KDNA asset signatures — RFC-0021 M1 (`kdsig.ed25519`).
+ *
+ * A `.kdna` container carries an optional top-level `signature.kdsig` entry:
+ * a JSON signature bundle whose Ed25519 signature covers a deterministic
+ * signing payload derived from the asset's canonical content digest
+ * (docs/CANONICALIZATION.md). Verification is offline and fail-closed: any
+ * malformed, unsupported, or unverifiable bundle rejects the asset.
+ *
+ * A signature proves integrity and provenance only. It never proves
+ * expertise, truthfulness, safety, or fitness for purpose.
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+
+const KDSIG_PROFILE = 'kdsig.ed25519';
+const KDSIG_PROFILE_VERSION = '0.1.0';
+const KDSIG_ALGORITHM = 'ed25519';
+const SIGNATURE_ENTRY_NAME = 'signature.kdsig';
+
+const RAW_PUBLIC_KEY_HEX_LENGTH = 64;
+const RAW_SIGNATURE_HEX_LENGTH = 128;
+const SHA256_HEX_LENGTH = 64;
+
+// RFC 8410 DER prefixes for raw Ed25519 key material.
+const PKCS8_ED25519_PREFIX = Buffer.from('302e020100300506032b657004220420', 'hex');
+const SPKI_ED25519_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+
+const BUNDLE_FIELDS = Object.freeze([
+  'algorithm',
+  'content_digest',
+  'profile',
+  'profile_version',
+  'public_key',
+  'signature',
+]);
+
+function sha256Hex(buf) {
+  return crypto.createHash('sha256').update(buf).digest('hex');
+}
+
+function signatureError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function isLowercaseHex(value, length) {
+  return typeof value === 'string' && value.length === length && /^[0-9a-f]+$/.test(value);
+}
+
+function assertContentDigestShape(value) {
+  if (
+    typeof value !== 'string'
+    || !value.startsWith('sha256:')
+    || !isLowercaseHex(value.slice('sha256:'.length), SHA256_HEX_LENGTH)
+  ) {
+    throw signatureError(
+      'KDNA_INTEGRITY_SIGNATURE_FAILED',
+      `signature bundle content_digest must be "sha256:<64 lowercase hex>", got ${JSON.stringify(value)}`,
+    );
+  }
+}
+
+/**
+ * Build the exact bytes that Ed25519 signs. The payload is domain-separated by
+ * the profile coordinate and binds the asset's canonical content digest, so a
+ * signature can never be replayed across profiles, versions, or assets.
+ */
+function buildSigningPayload(contentDigest) {
+  assertContentDigestShape(contentDigest);
+  return Buffer.from(`${KDSIG_PROFILE}:${KDSIG_PROFILE_VERSION}:${contentDigest}`, 'utf8');
+}
+
+function privateKeyObjectFromSeed(seedHex) {
+  if (!isLowercaseHex(seedHex, RAW_PUBLIC_KEY_HEX_LENGTH)) {
+    throw signatureError(
+      'KDNA_SIGNATURE_KEY_INVALID',
+      'Ed25519 private key must be a 32-byte seed encoded as 64 lowercase hex characters',
+    );
+  }
+  const der = Buffer.concat([PKCS8_ED25519_PREFIX, Buffer.from(seedHex, 'hex')]);
+  try {
+    return crypto.createPrivateKey({ key: der, format: 'der', type: 'pkcs8' });
+  } catch (e) {
+    throw signatureError('KDNA_SIGNATURE_KEY_INVALID', `invalid Ed25519 private key: ${e.message}`);
+  }
+}
+
+function publicKeyObjectFromRaw(publicKeyHex) {
+  if (!isLowercaseHex(publicKeyHex, RAW_PUBLIC_KEY_HEX_LENGTH)) {
+    throw signatureError(
+      'KDNA_INTEGRITY_SIGNATURE_FAILED',
+      'signature bundle public_key must be a 32-byte Ed25519 key encoded as 64 lowercase hex characters',
+    );
+  }
+  const der = Buffer.concat([SPKI_ED25519_PREFIX, Buffer.from(publicKeyHex, 'hex')]);
+  try {
+    return crypto.createPublicKey({ key: der, format: 'der', type: 'spki' });
+  } catch (e) {
+    throw signatureError(
+      'KDNA_INTEGRITY_SIGNATURE_FAILED',
+      `signature bundle public_key is not a valid Ed25519 key: ${e.message}`,
+    );
+  }
+}
+
+function rawPublicKeyHexFromObject(keyObject) {
+  const spki = keyObject.export({ format: 'der', type: 'spki' });
+  return spki.subarray(SPKI_ED25519_PREFIX.length).toString('hex');
+}
+
+/**
+ * Generate a new Ed25519 signing key pair. The private key is returned as the
+ * raw 32-byte seed in lowercase hex; custody is the signer's responsibility.
+ */
+function generateSigningKeyPair() {
+  const { privateKey, publicKey } = crypto.generateKeyPairSync('ed25519');
+  const pkcs8 = privateKey.export({ format: 'der', type: 'pkcs8' });
+  const seedHex = pkcs8.subarray(PKCS8_ED25519_PREFIX.length).toString('hex');
+  return {
+    algorithm: KDSIG_ALGORITHM,
+    private_key: seedHex,
+    public_key: rawPublicKeyHexFromObject(publicKey),
+  };
+}
+
+/**
+ * Fingerprint of a raw Ed25519 public key: sha256 over the 32 key bytes.
+ */
+function keyFingerprint(publicKeyHex) {
+  if (!isLowercaseHex(publicKeyHex, RAW_PUBLIC_KEY_HEX_LENGTH)) {
+    throw signatureError(
+      'KDNA_SIGNATURE_KEY_INVALID',
+      'keyFingerprint expects a 32-byte Ed25519 public key encoded as 64 lowercase hex characters',
+    );
+  }
+  return `sha256:${sha256Hex(Buffer.from(publicKeyHex, 'hex'))}`;
+}
+
+function stableStringify(value) {
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`)
+      .join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+/**
+ * Serialize a signature bundle to its canonical wire bytes (sorted keys, no
+ * insignificant whitespace). Verification accepts any JSON encoding of the
+ * same fields; canonical bytes are what signers and vectors pin.
+ */
+function serializeSignatureBundle(bundle) {
+  return Buffer.from(`${stableStringify(bundle)}\n`, 'utf8');
+}
+
+function parseSignatureBundle(bytes) {
+  let text;
+  try {
+    text = Buffer.isBuffer(bytes) ? bytes.toString('utf8') : String(bytes);
+  } catch (e) {
+    throw signatureError('KDNA_INTEGRITY_SIGNATURE_FAILED', `signature bundle is not UTF-8: ${e.message}`);
+  }
+  let bundle;
+  try {
+    bundle = JSON.parse(text);
+  } catch (e) {
+    throw signatureError(
+      'KDNA_INTEGRITY_SIGNATURE_FAILED',
+      `signature.kdsig is not valid JSON: ${e.message}`,
+    );
+  }
+  if (!bundle || typeof bundle !== 'object' || Array.isArray(bundle)) {
+    throw signatureError('KDNA_INTEGRITY_SIGNATURE_FAILED', 'signature bundle must be a JSON object');
+  }
+  for (const field of BUNDLE_FIELDS) {
+    if (typeof bundle[field] !== 'string') {
+      throw signatureError(
+        'KDNA_INTEGRITY_SIGNATURE_FAILED',
+        `signature bundle is missing required string field: ${field}`,
+      );
+    }
+  }
+  const extra = Object.keys(bundle).filter((key) => !BUNDLE_FIELDS.includes(key));
+  if (extra.length) {
+    throw signatureError(
+      'KDNA_INTEGRITY_SIGNATURE_FAILED',
+      `signature bundle carries unsupported fields: ${extra.sort().join(', ')}`,
+    );
+  }
+  if (bundle.profile !== KDSIG_PROFILE) {
+    throw signatureError(
+      'KDNA_SIGNATURE_PROFILE_UNSUPPORTED',
+      `signature bundle profile ${JSON.stringify(bundle.profile)} is not supported (supported: ${KDSIG_PROFILE})`,
+    );
+  }
+  if (bundle.profile_version !== KDSIG_PROFILE_VERSION) {
+    throw signatureError(
+      'KDNA_SIGNATURE_VERSION_UNSUPPORTED',
+      `signature bundle profile_version ${JSON.stringify(bundle.profile_version)} is not supported (supported: ${KDSIG_PROFILE_VERSION})`,
+    );
+  }
+  if (bundle.algorithm !== KDSIG_ALGORITHM) {
+    throw signatureError(
+      'KDNA_SIGNATURE_PROFILE_UNSUPPORTED',
+      `signature bundle algorithm ${JSON.stringify(bundle.algorithm)} is not supported (supported: ${KDSIG_ALGORITHM})`,
+    );
+  }
+  assertContentDigestShape(bundle.content_digest);
+  if (!isLowercaseHex(bundle.public_key, RAW_PUBLIC_KEY_HEX_LENGTH)) {
+    throw signatureError(
+      'KDNA_INTEGRITY_SIGNATURE_FAILED',
+      'signature bundle public_key must be 64 lowercase hex characters',
+    );
+  }
+  if (!isLowercaseHex(bundle.signature, RAW_SIGNATURE_HEX_LENGTH)) {
+    throw signatureError(
+      'KDNA_INTEGRITY_SIGNATURE_FAILED',
+      'signature bundle signature must be 128 lowercase hex characters',
+    );
+  }
+  return {
+    profile: bundle.profile,
+    profile_version: bundle.profile_version,
+    algorithm: bundle.algorithm,
+    content_digest: bundle.content_digest,
+    public_key: bundle.public_key,
+    signature: bundle.signature,
+  };
+}
+
+/**
+ * Sign a canonical content digest with an Ed25519 seed (64 lowercase hex).
+ * Returns the bundle object; serialize with serializeSignatureBundle().
+ */
+function signContentDigest(contentDigest, privateKeySeedHex) {
+  assertContentDigestShape(contentDigest);
+  const privateKey = privateKeyObjectFromSeed(privateKeySeedHex);
+  const publicKeyHex = rawPublicKeyHexFromObject(crypto.createPublicKey(privateKey));
+  const signatureBytes = crypto.sign(null, buildSigningPayload(contentDigest), privateKey);
+  return {
+    algorithm: KDSIG_ALGORITHM,
+    content_digest: contentDigest,
+    profile: KDSIG_PROFILE,
+    profile_version: KDSIG_PROFILE_VERSION,
+    public_key: publicKeyHex,
+    signature: signatureBytes.toString('hex'),
+  };
+}
+
+/**
+ * Verify a parsed bundle against a canonical content digest. Fail-closed:
+ * every mismatch throws with a stable error code. Returns verification
+ * evidence on success.
+ */
+function verifySignatureBundle(bundle, contentDigest, options = {}) {
+  const parsed = parseSignatureBundle(bundle);
+  assertContentDigestShape(contentDigest);
+  if (parsed.content_digest !== contentDigest) {
+    throw signatureError(
+      'KDNA_INTEGRITY_SIGNATURE_FAILED',
+      `signature bundle content_digest ${parsed.content_digest} does not match the asset content_digest ${contentDigest}`,
+    );
+  }
+  if (
+    typeof options.expectedPublicKey === 'string'
+    && options.expectedPublicKey.toLowerCase() !== parsed.public_key
+  ) {
+    throw signatureError(
+      'KDNA_INTEGRITY_SIGNATURE_FAILED',
+      'signature bundle public_key does not match the expected pinned key',
+    );
+  }
+  const publicKey = publicKeyObjectFromRaw(parsed.public_key);
+  const signatureBytes = Buffer.from(parsed.signature, 'hex');
+  let valid;
+  try {
+    valid = crypto.verify(null, buildSigningPayload(contentDigest), publicKey, signatureBytes);
+  } catch (e) {
+    throw signatureError(
+      'KDNA_INTEGRITY_SIGNATURE_FAILED',
+      `Ed25519 verification error: ${e.message}`,
+    );
+  }
+  if (valid !== true) {
+    throw signatureError(
+      'KDNA_INTEGRITY_SIGNATURE_FAILED',
+      'Ed25519 signature verification failed: signature does not match the canonical signing payload',
+    );
+  }
+  return {
+    state: 'verified',
+    profile: parsed.profile,
+    profile_version: parsed.profile_version,
+    algorithm: parsed.algorithm,
+    content_digest: parsed.content_digest,
+    public_key: parsed.public_key,
+    key_fingerprint: keyFingerprint(parsed.public_key),
+  };
+}
+
+module.exports = {
+  KDSIG_PROFILE,
+  KDSIG_PROFILE_VERSION,
+  KDSIG_ALGORITHM,
+  SIGNATURE_ENTRY_NAME,
+  buildSigningPayload,
+  generateSigningKeyPair,
+  keyFingerprint,
+  parseSignatureBundle,
+  serializeSignatureBundle,
+  signContentDigest,
+  verifySignatureBundle,
+};