@aikdna/kdna-core 0.15.12 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## v0.16.0 (2026-07-13)
+
+### Added
+
+- RFC-0019 external account/device key grants, schemas, deterministic golden
+  and negative fixtures, and JS/Swift parity vectors.
+- JS Core helpers for external envelope encryption, per-device grant issuance,
+  signature/binding verification, in-memory decryption, and explicit zeroization.
+- LoadPlan accepts only a runtime-verified external entitlement for account/org
+  assets; structurally similar status objects no longer authorize loading.
+- Reject authoring source directories at the public runtime API boundary;
+  `planLoad`, `load`, `loadAsset`, and `loadAuthorized` now require a packaged
+  `.kdna` file, including resolver-provided dependencies.
+- Regenerate authorization conformance fixtures from packaged assets and keep
+  source directories available only to authoring operations such as inspect,
+  validate, pack, and unpack.
+- Remove stale public format-generation wording and local coordination-path
+  assumptions from protocol documentation and public audit scripts.
+- Make release readiness fail for dirty inputs or when the selected version
+  tag does not point to the current commit.
+
+### Security
+
+- Account/device envelopes never fall back to the password profile.
+- Revoked, expired, tampered, digest/version/account/device mismatches fail
+  closed before Runtime Capsule projection.
+
 ## v0.15.12 (2026-07-12)
 
 **Single-format refactor + CBOR wire contract + Runtime Capsule.**

package/README.md

@@ -97,6 +97,18 @@ A `.kdna` asset contains:
 encryption envelope in the same entry; authorized plaintext is decrypted in
 memory and projected into the Runtime Capsule.
 
+### Account/device external grants
+
+RFC-0019 licensed assets can keep the encrypted container publicly available
+while an issuer grants independent account/device access. `authorizeExternalKeyGrant()`
+verifies the issuer signature, lease, revocation state, account, device, asset
+UID/version/digest, and encrypted entry before returning a branded entitlement
+and in-memory decrypt hook. A plain `{status: "active"}` object is not accepted.
+
+Device private keys belong in the platform SecretStore. The returned session
+must be disposed after loading; Agent-facing callers should receive only the
+Runtime Capsule. Account grants never fall back to the password profile.
+
 ## Load Profiles
 
 `loadAuthorized()` supports:

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@aikdna/kdna-core",
-    "version": "0.15.12",
+    "version": "0.16.0",
     "description": "KDNA Core library for validating, planning, and loading local .kdna judgment assets.",
     "engines": {
         "node": ">=18.0.0"

package/schema/kdna-envelope-external-grant-v1.schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kdna.ai/specs/kdna-envelope-external-grant-v1.schema.json",
+  "title": "KDNA external grant envelope v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["profile", "alg", "cek_derivation", "key_ref", "issuer_key_id", "entry_path", "plaintext_digest", "iv", "tag", "ciphertext"],
+  "properties": {
+    "profile": { "const": "kdna-envelope-external-grant-v1" },
+    "alg": { "const": "A256GCM" },
+    "cek_derivation": { "const": "HKDF-SHA256" },
+    "key_ref": { "type": "string", "minLength": 1, "maxLength": 256 },
+    "issuer_key_id": { "type": "string", "minLength": 1, "maxLength": 128 },
+    "entry_path": { "type": "string", "pattern": "^[^/].*[^/]$|^[^/]$", "maxLength": 256 },
+    "plaintext_digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "iv": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16}$" },
+    "tag": { "type": "string", "pattern": "^[A-Za-z0-9_-]{22}$" },
+    "ciphertext": { "type": "string", "minLength": 1, "pattern": "^[A-Za-z0-9_-]+$" }
+  }
+}

package/schema/kdna-key-grant-v1.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kdna.ai/specs/kdna-key-grant-v1.schema.json",
+  "title": "KDNA account/device external key grant v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["profile", "grant_id", "issuer", "signing_key_id", "entitlement_id", "account_id", "device_id", "device_public_key", "device_signing_public_key", "asset", "issued_at", "refresh_after", "offline_grace_until", "expires_at", "status", "status_version", "wrap", "signature"],
+  "properties": {
+    "profile": { "const": "kdna-key-grant-v1" },
+    "grant_id": { "$ref": "#/$defs/id" },
+    "issuer": { "type": "string", "format": "uri", "maxLength": 256 },
+    "signing_key_id": { "$ref": "#/$defs/id" },
+    "entitlement_id": { "$ref": "#/$defs/id" },
+    "account_id": { "$ref": "#/$defs/id" },
+    "device_id": { "$ref": "#/$defs/id" },
+    "device_public_key": { "type": "string", "pattern": "^x25519:[A-Za-z0-9_-]{43}$" },
+    "device_signing_public_key": { "type": "string", "pattern": "^ed25519:[A-Za-z0-9_-]{43}$" },
+    "asset": {
+      "type": "object", "additionalProperties": false,
+      "required": ["asset_id", "asset_uid", "version", "digest", "entry_path", "ciphertext_digest", "key_ref", "issuer_key_id"],
+      "properties": {
+        "asset_id": { "type": "string", "minLength": 1, "maxLength": 256 },
+        "asset_uid": { "type": "string", "minLength": 1, "maxLength": 512 },
+        "version": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "digest": { "$ref": "#/$defs/digest" },
+        "entry_path": { "type": "string", "minLength": 1, "maxLength": 256 },
+        "ciphertext_digest": { "$ref": "#/$defs/digest" },
+        "key_ref": { "type": "string", "minLength": 1, "maxLength": 256 },
+        "issuer_key_id": { "$ref": "#/$defs/id" }
+      }
+    },
+    "issued_at": { "type": "string", "format": "date-time" },
+    "refresh_after": { "type": "string", "format": "date-time" },
+    "offline_grace_until": { "type": "string", "format": "date-time" },
+    "expires_at": { "type": "string", "format": "date-time" },
+    "status": { "enum": ["active", "revoked", "expired"] },
+    "status_version": { "type": "integer", "minimum": 1 },
+    "wrap": {
+      "type": "object", "additionalProperties": false,
+      "required": ["alg", "ephemeral_public_key", "salt", "wrapped_cek"],
+      "properties": {
+        "alg": { "const": "X25519-HKDF-SHA256+A256KW" },
+        "ephemeral_public_key": { "type": "string", "pattern": "^x25519:[A-Za-z0-9_-]{43}$" },
+        "salt": { "type": "string", "pattern": "^[A-Za-z0-9_-]{22}$" },
+        "wrapped_cek": { "type": "string", "pattern": "^[A-Za-z0-9_-]{54}$" }
+      }
+    },
+    "signature": { "type": "string", "pattern": "^ed25519:[A-Za-z0-9_-]{86}$" }
+  },
+  "$defs": {
+    "id": { "type": "string", "pattern": "^[A-Za-z0-9._:@/-]{1,256}$" },
+    "digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }
+  }
+}

package/schema/load-plan.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/aikdna/kdna/schema/load-plan.schema.json",
   "title": "KDNA LoadPlan v1",
-  "description": "Machine-readable pre-load authorization and runtime planning result for KDNA Core v1 assets.",
+  "description": "Machine-readable pre-load authorization and runtime planning result for packaged KDNA assets.",
   "type": "object",
   "required": [
     "kdna_version",

package/src/external-key-grant.js

@@ -0,0 +1,560 @@
+/**
+ * Account/device external key grants (RFC-0019).
+ *
+ * This module deliberately has no password or license-key fallback. Asset CEKs
+ * are derived from an issuer root only in memory, then re-wrapped to one X25519
+ * device key by a signed, short-lived grant.
+ */
+
+const crypto = require('node:crypto');
+const path = require('node:path');
+const Ajv2020 = require('ajv/dist/2020');
+const addFormats = require('ajv-formats');
+const cbor = require('cbor-x');
+const { hkdfSha256, aesWrap, aesUnwrap } = require('./crypto-profile');
+
+const EXTERNAL_ENVELOPE_PROFILE = 'kdna-envelope-external-grant-v1';
+const EXTERNAL_GRANT_PROFILE = 'kdna-key-grant-v1';
+const EXTERNAL_AAD_PROFILE = 'kdna-external-asset-cek-v1';
+const DEVICE_KEK_PROFILE = 'kdna-device-grant-kek-v1';
+const ENVELOPE_ALG = 'A256GCM';
+const GRANT_WRAP_ALG = 'X25519-HKDF-SHA256+A256KW';
+
+const schemaRoot = path.join(__dirname, '..', 'schema');
+const ajv = new Ajv2020({ allErrors: true, strict: true });
+addFormats(ajv);
+const validateEnvelopeSchema = ajv.compile(
+  require(path.join(schemaRoot, 'kdna-envelope-external-grant-v1.schema.json')),
+);
+const validateGrantSchema = ajv.compile(
+  require(path.join(schemaRoot, 'kdna-key-grant-v1.schema.json')),
+);
+
+const verifiedEntitlements = new WeakSet();
+
+class KDNAExternalGrantError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'KDNAExternalGrantError';
+    this.code = code;
+  }
+}
+
+function fail(code, message) {
+  throw new KDNAExternalGrantError(code, message);
+}
+
+function sha256(value) {
+  return crypto.createHash('sha256').update(value).digest();
+}
+
+function digest(value) {
+  return `sha256:${sha256(value).toString('hex')}`;
+}
+
+function b64url(value) {
+  return Buffer.from(value).toString('base64url');
+}
+
+function decodeB64url(value, label, expectedLength) {
+  if (typeof value !== 'string' || !/^[A-Za-z0-9_-]+$/.test(value)) {
+    fail('KDNA_GRANT_FORMAT_INVALID', `${label} is not canonical base64url`);
+  }
+  const out = Buffer.from(value, 'base64url');
+  if (b64url(out) !== value || (expectedLength != null && out.length !== expectedLength)) {
+    fail('KDNA_GRANT_FORMAT_INVALID', `${label} has an invalid length or encoding`);
+  }
+  return out;
+}
+
+function prefixedKey(value, prefix, label, expectedLength = 32) {
+  if (typeof value !== 'string' || !value.startsWith(`${prefix}:`)) {
+    fail('KDNA_GRANT_FORMAT_INVALID', `${label} must use ${prefix}`);
+  }
+  return decodeB64url(value.slice(prefix.length + 1), label, expectedLength);
+}
+
+function canonicalJson(value) {
+  if (value === null || typeof value === 'boolean' || typeof value === 'number') {
+    return JSON.stringify(value);
+  }
+  if (typeof value === 'string') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  if (typeof value === 'object') {
+    return `{${Object.keys(value)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`)
+      .join(',')}}`;
+  }
+  throw new TypeError(`unsupported canonical JSON value: ${typeof value}`);
+}
+
+function grantSigningPayload(grant) {
+  const unsigned = { ...grant };
+  delete unsigned.signature;
+  return Buffer.from(canonicalJson(unsigned), 'utf8');
+}
+
+function schemaProblems(validator) {
+  return (validator.errors || [])
+    .slice(0, 4)
+    .map((error) => `${error.instancePath || '<root>'} ${error.message}`)
+    .join('; ');
+}
+
+function validateExternalEnvelope(envelope) {
+  if (!validateEnvelopeSchema(envelope)) {
+    fail('KDNA_ENVELOPE_FORMAT_INVALID', `external envelope is invalid: ${schemaProblems(validateEnvelopeSchema)}`);
+  }
+  return envelope;
+}
+
+function validateExternalKeyGrant(grant) {
+  if (!validateGrantSchema(grant)) {
+    fail('KDNA_GRANT_FORMAT_INVALID', `external key grant is invalid: ${schemaProblems(validateGrantSchema)}`);
+  }
+  const issued = Date.parse(grant.issued_at);
+  const refresh = Date.parse(grant.refresh_after);
+  const grace = Date.parse(grant.offline_grace_until);
+  const expires = Date.parse(grant.expires_at);
+  if (!(issued <= refresh && refresh <= grace && grace <= expires)) {
+    fail('KDNA_GRANT_TIME_INVALID', 'grant time window is not monotonic');
+  }
+  return grant;
+}
+
+function externalEnvelopeAad({ manifest, entryName, plaintextDigest, keyRef, issuerKeyId }) {
+  const entitlementProfile = manifest?.entitlement?.profile || '';
+  const fields = [
+    EXTERNAL_ENVELOPE_PROFILE,
+    manifest?.asset_uid || '',
+    manifest?.asset_id || manifest?.name || '',
+    manifest?.version || '',
+    entryName,
+    plaintextDigest,
+    keyRef,
+    issuerKeyId,
+    manifest?.access || '',
+    entitlementProfile,
+  ];
+  if (fields.some((field) => typeof field !== 'string' || field.length === 0)) {
+    fail('KDNA_ENVELOPE_BINDING_INVALID', 'manifest is missing an external envelope binding');
+  }
+  if (manifest.access !== 'licensed' || !['account', 'org'].includes(entitlementProfile)) {
+    fail('KDNA_ENVELOPE_BINDING_INVALID', 'external grants require licensed account or org entitlement');
+  }
+  return Buffer.from(fields.join('\n'), 'utf8');
+}
+
+function normalizeIssuerRoot(value) {
+  const root = Buffer.isBuffer(value) ? Buffer.from(value) : decodeB64url(value, 'issuer root', 32);
+  if (root.length !== 32) fail('KDNA_ISSUER_ROOT_INVALID', 'issuer root must be 32 bytes');
+  return root;
+}
+
+function deriveExternalAssetCek({ issuerRootKey, manifest, entryName, plaintextDigest, keyRef, issuerKeyId }) {
+  const root = normalizeIssuerRoot(issuerRootKey);
+  const aad = externalEnvelopeAad({ manifest, entryName, plaintextDigest, keyRef, issuerKeyId });
+  try {
+    return hkdfSha256(
+      root,
+      sha256(aad),
+      Buffer.from(`${EXTERNAL_AAD_PROFILE}\n${keyRef}`, 'utf8'),
+      32,
+    );
+  } finally {
+    root.fill(0);
+  }
+}
+
+function encodeExternalEnvelope(envelope) {
+  validateExternalEnvelope(envelope);
+  return Buffer.from(cbor.encode(envelope));
+}
+
+function decodeExternalEnvelope(value) {
+  let envelope = value;
+  if (Buffer.isBuffer(value) || value instanceof Uint8Array) {
+    try {
+      envelope = cbor.decode(Buffer.from(value));
+    } catch {
+      fail('KDNA_ENVELOPE_FORMAT_INVALID', 'external envelope CBOR could not be decoded');
+    }
+  }
+  return validateExternalEnvelope(envelope);
+}
+
+function encryptExternalGrantEntry(plaintextValue, options = {}) {
+  const plaintext = Buffer.from(plaintextValue);
+  const {
+    manifest,
+    entryName = 'payload.kdnab',
+    issuerRootKey,
+    keyRef,
+    issuerKeyId,
+    iv = crypto.randomBytes(12),
+  } = options;
+  const plaintextDigest = digest(plaintext);
+  const aad = externalEnvelopeAad({ manifest, entryName, plaintextDigest, keyRef, issuerKeyId });
+  const cek = deriveExternalAssetCek({
+    issuerRootKey,
+    manifest,
+    entryName,
+    plaintextDigest,
+    keyRef,
+    issuerKeyId,
+  });
+  try {
+    const cipher = crypto.createCipheriv('aes-256-gcm', cek, Buffer.from(iv));
+    cipher.setAAD(aad);
+    const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    return {
+      profile: EXTERNAL_ENVELOPE_PROFILE,
+      alg: ENVELOPE_ALG,
+      cek_derivation: 'HKDF-SHA256',
+      key_ref: keyRef,
+      issuer_key_id: issuerKeyId,
+      entry_path: entryName,
+      plaintext_digest: plaintextDigest,
+      iv: b64url(iv),
+      tag: b64url(cipher.getAuthTag()),
+      ciphertext: b64url(ciphertext),
+    };
+  } finally {
+    cek.fill(0);
+  }
+}
+
+function publicKeyFromRaw(crv, value) {
+  const x = value.includes(':') ? value.split(':', 2)[1] : value;
+  return crypto.createPublicKey({ key: { kty: 'OKP', crv, x }, format: 'jwk' });
+}
+
+function privateKeyFromBundle(crv, bundle) {
+  if (bundle && typeof bundle === 'object' && bundle.type === 'private') return bundle;
+  if (bundle && bundle.privateKey) return bundle.privateKey;
+  const privateValue = bundle?.private_key || bundle?.privateKeyRaw || bundle?.d;
+  const publicValue = bundle?.public_key || bundle?.publicKeyRaw || bundle?.x;
+  if (!privateValue || !publicValue) {
+    fail('KDNA_GRANT_DEVICE_KEY_INVALID', `${crv} private and public key material are required`);
+  }
+  const d = privateValue.includes(':') ? privateValue.split(':', 2)[1] : privateValue;
+  const x = publicValue.includes(':') ? publicValue.split(':', 2)[1] : publicValue;
+  decodeB64url(d, `${crv} private key`, 32);
+  decodeB64url(x, `${crv} public key`, 32);
+  return crypto.createPrivateKey({ key: { kty: 'OKP', crv, d, x }, format: 'jwk' });
+}
+
+function generateDeviceKeyPairs() {
+  const agreement = crypto.generateKeyPairSync('x25519');
+  const signing = crypto.generateKeyPairSync('ed25519');
+  const agreementPublic = agreement.publicKey.export({ format: 'jwk' });
+  const agreementPrivate = agreement.privateKey.export({ format: 'jwk' });
+  const signingPublic = signing.publicKey.export({ format: 'jwk' });
+  const signingPrivate = signing.privateKey.export({ format: 'jwk' });
+  return {
+    agreement: {
+      public_key: `x25519:${agreementPublic.x}`,
+      private_key: `x25519:${agreementPrivate.d}`,
+    },
+    signing: {
+      public_key: `ed25519:${signingPublic.x}`,
+      private_key: `ed25519:${signingPrivate.d}`,
+    },
+  };
+}
+
+function resolveIssuerPublicKey(issuerPublicKeys, keyId) {
+  const value = issuerPublicKeys instanceof Map ? issuerPublicKeys.get(keyId) : issuerPublicKeys?.[keyId];
+  if (!value) fail('KDNA_GRANT_ISSUER_UNKNOWN', 'grant signing key is not pinned');
+  if (value && typeof value === 'object' && value.type === 'public') return value;
+  if (typeof value === 'string' && value.startsWith('ed25519:')) {
+    try {
+      const raw = prefixedKey(value, 'ed25519', 'grant issuer public key');
+      return publicKeyFromRaw('Ed25519', `ed25519:${b64url(raw)}`);
+    } catch {
+      fail('KDNA_GRANT_ISSUER_UNKNOWN', 'grant signing key is invalid');
+    }
+  }
+  try {
+    return crypto.createPublicKey(value);
+  } catch {
+    fail('KDNA_GRANT_ISSUER_UNKNOWN', 'grant signing key is invalid');
+  }
+}
+
+function createExternalKeyGrant(options = {}) {
+  const {
+    issuerRootKey,
+    issuerSigningPrivateKey,
+    signingKeyId,
+    issuer,
+    entitlementId,
+    accountId,
+    deviceId,
+    devicePublicKey,
+    deviceSigningPublicKey,
+    manifest,
+    envelope: envelopeValue,
+    assetDigest,
+    status = 'active',
+    statusVersion = 1,
+    issuedAt = new Date(),
+    refreshAfter = new Date(issuedAt.getTime() + 24 * 60 * 60 * 1000),
+    offlineGraceUntil = new Date(issuedAt.getTime() + 7 * 24 * 60 * 60 * 1000),
+    expiresAt = new Date(issuedAt.getTime() + 8 * 24 * 60 * 60 * 1000),
+    grantId = `grt_${crypto.randomBytes(16).toString('base64url')}`,
+    ephemeralKeyPair = null,
+    wrapSalt = null,
+  } = options;
+  const envelope = decodeExternalEnvelope(envelopeValue);
+  const deviceRaw = prefixedKey(devicePublicKey, 'x25519', 'device public key');
+  prefixedKey(deviceSigningPublicKey, 'ed25519', 'device signing public key');
+  const cek = deriveExternalAssetCek({
+    issuerRootKey,
+    manifest,
+    entryName: envelope.entry_path,
+    plaintextDigest: envelope.plaintext_digest,
+    keyRef: envelope.key_ref,
+    issuerKeyId: envelope.issuer_key_id,
+  });
+  let shared = null;
+  let kek = null;
+  try {
+    const ephemeral = ephemeralKeyPair || crypto.generateKeyPairSync('x25519');
+    const ephemeralJwk = ephemeral.publicKey.export({ format: 'jwk' });
+    const deviceKey = publicKeyFromRaw('X25519', `x25519:${b64url(deviceRaw)}`);
+    shared = crypto.diffieHellman({ privateKey: ephemeral.privateKey, publicKey: deviceKey });
+    const salt = wrapSalt ? Buffer.from(wrapSalt) : crypto.randomBytes(16);
+    if (salt.length !== 16) fail('KDNA_GRANT_FORMAT_INVALID', 'grant wrap salt must be 16 bytes');
+    kek = hkdfSha256(shared, salt, Buffer.from(`${DEVICE_KEK_PROFILE}\n${grantId}`, 'utf8'), 32);
+    const grant = {
+      profile: EXTERNAL_GRANT_PROFILE,
+      grant_id: grantId,
+      issuer,
+      signing_key_id: signingKeyId,
+      entitlement_id: entitlementId,
+      account_id: accountId,
+      device_id: deviceId,
+      device_public_key: devicePublicKey,
+      device_signing_public_key: deviceSigningPublicKey,
+      asset: {
+        asset_id: manifest.asset_id || manifest.name,
+        asset_uid: manifest.asset_uid,
+        version: manifest.version,
+        digest: assetDigest,
+        entry_path: envelope.entry_path,
+        ciphertext_digest: digest(Buffer.from(envelope.ciphertext, 'base64url')),
+        key_ref: envelope.key_ref,
+        issuer_key_id: envelope.issuer_key_id,
+      },
+      issued_at: new Date(issuedAt).toISOString(),
+      refresh_after: new Date(refreshAfter).toISOString(),
+      offline_grace_until: new Date(offlineGraceUntil).toISOString(),
+      expires_at: new Date(expiresAt).toISOString(),
+      status,
+      status_version: statusVersion,
+      wrap: {
+        alg: GRANT_WRAP_ALG,
+        ephemeral_public_key: `x25519:${ephemeralJwk.x}`,
+        salt: b64url(salt),
+        wrapped_cek: b64url(aesWrap(kek, cek)),
+      },
+    };
+    validateExternalKeyGrant({ ...grant, signature: `ed25519:${'A'.repeat(86)}` });
+    const signature = crypto.sign(null, grantSigningPayload(grant), issuerSigningPrivateKey);
+    return { ...grant, signature: `ed25519:${b64url(signature)}` };
+  } finally {
+    cek.fill(0);
+    if (shared) shared.fill(0);
+    if (kek) kek.fill(0);
+  }
+}
+
+function grantState(grant, now, networkAvailable, allowOffline) {
+  const time = now instanceof Date ? now.getTime() : new Date(now || Date.now()).getTime();
+  const issued = Date.parse(grant.issued_at);
+  const refresh = Date.parse(grant.refresh_after);
+  const grace = Date.parse(grant.offline_grace_until);
+  const expires = Date.parse(grant.expires_at);
+  if (
+    ![time, issued, refresh, grace, expires].every(Number.isFinite) ||
+    issued > refresh || refresh > grace || grace > expires
+  ) fail('KDNA_GRANT_TIME_INVALID', 'external key grant time window is invalid');
+  if (time + 5 * 60 * 1000 < issued) fail('KDNA_GRANT_TIME_INVALID', 'external key grant is not valid yet');
+  if (grant.status === 'revoked') fail('KDNA_GRANT_REVOKED', 'external key grant is revoked');
+  if (grant.status !== 'active') fail('KDNA_GRANT_EXPIRED', 'external key grant is not active');
+  if (time > expires) fail('KDNA_GRANT_EXPIRED', 'external key grant has expired');
+  if (time <= refresh) return 'active';
+  if (networkAvailable) fail('KDNA_GRANT_SYNC_REQUIRED', 'external key grant must be synchronized');
+  if (!allowOffline || time > grace) {
+    fail('KDNA_GRANT_EXPIRED', 'external key grant offline grace has expired');
+  }
+  return 'offline_grace';
+}
+
+function expectEqual(actual, expected, code, label) {
+  if (expected == null || actual !== expected) fail(code, `${label} mismatch`);
+}
+
+function authorizeExternalKeyGrant(options = {}) {
+  const {
+    grant,
+    issuerPublicKeys,
+    manifest,
+    checksums,
+    envelope: envelopeValue,
+    deviceAgreementKey,
+    expectedAccountId,
+    expectedDeviceId,
+    expectedDeviceSigningPublicKey,
+    minimumStatusVersion = null,
+    now = new Date(),
+    networkAvailable = false,
+    allowOffline = true,
+  } = options;
+  validateExternalKeyGrant(grant);
+  if (minimumStatusVersion != null && (
+    !Number.isInteger(minimumStatusVersion) || grant.status_version < minimumStatusVersion
+  )) fail('KDNA_GRANT_ROLLBACK_DETECTED', 'external key grant status version rolled back');
+  const issuerKey = resolveIssuerPublicKey(issuerPublicKeys, grant.signing_key_id);
+  const signature = prefixedKey(grant.signature, 'ed25519', 'grant signature', 64);
+  if (signature.length !== 64 || !crypto.verify(null, grantSigningPayload(grant), issuerKey, signature)) {
+    fail('KDNA_GRANT_SIGNATURE_INVALID', 'external key grant signature is invalid');
+  }
+  const state = grantState(grant, now, networkAvailable, allowOffline);
+  const envelope = decodeExternalEnvelope(envelopeValue);
+
+  expectEqual(grant.account_id, expectedAccountId, 'KDNA_GRANT_ACCOUNT_MISMATCH', 'grant account');
+  expectEqual(grant.device_id, expectedDeviceId, 'KDNA_GRANT_DEVICE_MISMATCH', 'grant device');
+  expectEqual(
+    grant.device_signing_public_key,
+    expectedDeviceSigningPublicKey,
+    'KDNA_GRANT_DEVICE_MISMATCH',
+    'device signing key',
+  );
+  expectEqual(grant.asset.asset_id, manifest.asset_id || manifest.name, 'KDNA_GRANT_ASSET_MISMATCH', 'asset ID');
+  expectEqual(grant.asset.asset_uid, manifest.asset_uid, 'KDNA_GRANT_ASSET_MISMATCH', 'asset UID');
+  expectEqual(grant.asset.version, manifest.version, 'KDNA_GRANT_ASSET_MISMATCH', 'asset version');
+  expectEqual(grant.asset.digest, checksums?.asset_digest, 'KDNA_GRANT_DIGEST_MISMATCH', 'asset digest');
+  expectEqual(grant.asset.entry_path, envelope.entry_path, 'KDNA_GRANT_ASSET_MISMATCH', 'entry path');
+  expectEqual(grant.asset.key_ref, envelope.key_ref, 'KDNA_GRANT_ASSET_MISMATCH', 'key reference');
+  expectEqual(grant.asset.issuer_key_id, envelope.issuer_key_id, 'KDNA_GRANT_ASSET_MISMATCH', 'issuer asset key');
+  expectEqual(
+    grant.asset.ciphertext_digest,
+    digest(Buffer.from(envelope.ciphertext, 'base64url')),
+    'KDNA_GRANT_DIGEST_MISMATCH',
+    'ciphertext digest',
+  );
+
+  const privateKey = privateKeyFromBundle('X25519', deviceAgreementKey);
+  const localPublic = deviceAgreementKey.public_key || deviceAgreementKey.publicKeyRaw || deviceAgreementKey.x;
+  expectEqual(grant.device_public_key, localPublic, 'KDNA_GRANT_DEVICE_MISMATCH', 'device agreement key');
+  const ephemeralRaw = prefixedKey(grant.wrap.ephemeral_public_key, 'x25519', 'ephemeral public key');
+  const ephemeralKey = publicKeyFromRaw('X25519', `x25519:${b64url(ephemeralRaw)}`);
+  const shared = crypto.diffieHellman({ privateKey, publicKey: ephemeralKey });
+  const salt = decodeB64url(grant.wrap.salt, 'grant wrap salt', 16);
+  const kek = hkdfSha256(shared, salt, Buffer.from(`${DEVICE_KEK_PROFILE}\n${grant.grant_id}`, 'utf8'), 32);
+  let cek;
+  try {
+    cek = aesUnwrap(kek, decodeB64url(grant.wrap.wrapped_cek, 'wrapped CEK', 40));
+  } catch {
+    fail('KDNA_GRANT_DEVICE_MISMATCH', 'device could not unwrap the external key grant');
+  } finally {
+    shared.fill(0);
+    kek.fill(0);
+  }
+
+  const assetBinding = Object.freeze({
+    asset_id: grant.asset.asset_id,
+    asset_uid: grant.asset.asset_uid,
+    version: grant.asset.version,
+    digest: grant.asset.digest,
+    entry_path: grant.asset.entry_path,
+    ciphertext_digest: grant.asset.ciphertext_digest,
+    key_ref: grant.asset.key_ref,
+    issuer_key_id: grant.asset.issuer_key_id,
+  });
+  const entitlement = Object.freeze({
+    status: state,
+    profile: EXTERNAL_GRANT_PROFILE,
+    grant_id: grant.grant_id,
+    entitlement_id: grant.entitlement_id,
+    account_id: grant.account_id,
+    device_id: grant.device_id,
+    refresh_after: grant.refresh_after,
+    offline_grace_until: grant.offline_grace_until,
+    expires_at: grant.expires_at,
+    asset: assetBinding,
+  });
+  verifiedEntitlements.add(entitlement);
+
+  const decryptEntry = ({ entryName, ciphertext, manifest: runtimeManifest }) => {
+    const runtimeEnvelope = decodeExternalEnvelope(ciphertext);
+    if (entryName !== envelope.entry_path) fail('KDNA_GRANT_ASSET_MISMATCH', 'encrypted entry path mismatch');
+    if (digest(Buffer.from(runtimeEnvelope.ciphertext, 'base64url')) !== grant.asset.ciphertext_digest) {
+      fail('KDNA_GRANT_DIGEST_MISMATCH', 'encrypted entry digest mismatch');
+    }
+    const aad = externalEnvelopeAad({
+      manifest: runtimeManifest,
+      entryName,
+      plaintextDigest: runtimeEnvelope.plaintext_digest,
+      keyRef: runtimeEnvelope.key_ref,
+      issuerKeyId: runtimeEnvelope.issuer_key_id,
+    });
+    try {
+      const decipher = crypto.createDecipheriv(
+        'aes-256-gcm',
+        cek,
+        decodeB64url(runtimeEnvelope.iv, 'envelope IV', 12),
+      );
+      decipher.setAAD(aad);
+      decipher.setAuthTag(decodeB64url(runtimeEnvelope.tag, 'envelope tag', 16));
+      const plaintext = Buffer.concat([
+        decipher.update(decodeB64url(runtimeEnvelope.ciphertext, 'envelope ciphertext')),
+        decipher.final(),
+      ]);
+      if (digest(plaintext) !== runtimeEnvelope.plaintext_digest) {
+        fail('KDNA_GRANT_DIGEST_MISMATCH', 'decrypted entry digest mismatch');
+      }
+      return plaintext;
+    } catch (error) {
+      if (error instanceof KDNAExternalGrantError) throw error;
+      fail('KDNA_GRANT_TAMPERED', 'external envelope authentication failed');
+    }
+  };
+
+  return {
+    entitlement,
+    decryptEntry,
+    dispose() {
+      if (cek) cek.fill(0);
+      cek = null;
+    },
+  };
+}
+
+function isVerifiedExternalEntitlement(value) {
+  return !!value && verifiedEntitlements.has(value);
+}
+
+module.exports = {
+  EXTERNAL_ENVELOPE_PROFILE,
+  EXTERNAL_GRANT_PROFILE,
+  EXTERNAL_AAD_PROFILE,
+  DEVICE_KEK_PROFILE,
+  KDNAExternalGrantError,
+  canonicalJson,
+  grantSigningPayload,
+  validateExternalEnvelope,
+  validateExternalKeyGrant,
+  externalEnvelopeAad,
+  deriveExternalAssetCek,
+  encodeExternalEnvelope,
+  decodeExternalEnvelope,
+  encryptExternalGrantEntry,
+  generateDeviceKeyPairs,
+  createExternalKeyGrant,
+  authorizeExternalKeyGrant,
+  isVerifiedExternalEntitlement,
+};

package/src/index.js

@@ -8,9 +8,11 @@ const render = require('./render');
 const compose = require('./compose');
 const assetReader = require('./asset-reader');
 const cryptoProfile = require('./crypto-profile');
+const externalKeyGrant = require('./external-key-grant');
 const publicApi = require('./public-api');
 const workpackPure = require('./workpack-pure');
 const v1 = require('./v1');
+const runtimeApi = require('./runtime-api');
 
 module.exports = {
   ...publicApi,
@@ -21,6 +23,8 @@ module.exports = {
   ...compose,
   ...assetReader,
   ...cryptoProfile,
+  ...externalKeyGrant,
   ...workpackPure,
   ...v1,
+  ...runtimeApi,
 };

package/src/index.mjs

@@ -20,13 +20,9 @@ export {
   readLayout,
   inspect,
   validate,
-  planLoad,
-  loadAuthorized,
   buildChecksums,
   pack,
   unpack,
-  load,
-  loadAsset,
   buildCapsule,
   FORBIDDEN_OUTPUT_TERMS,
   parseSemver,
@@ -34,6 +30,12 @@ export {
   satisfies,
 } from './v1/index.js';
 
+import runtimeApi from './runtime-api.js';
+export const planLoad = runtimeApi.planLoad;
+export const loadAuthorized = runtimeApi.loadAuthorized;
+export const load = runtimeApi.load;
+export const loadAsset = runtimeApi.loadAsset;
+
 export { validateDomainSchema, validateCrossFile } from './validate-pure.js';
 
 export { renderPreviewHTML, escHtml, renderCard } from './render.js';
@@ -42,6 +44,7 @@ export { composeContext, composeContextWithAttribution, classifySignals, classif
 
 import assetReader from './asset-reader.js';
 import cryptoProfile from './crypto-profile.js';
+import externalKeyGrant from './external-key-grant.js';
 
 export const STANDARD_ENTRIES = assetReader.STANDARD_ENTRIES;
 export const createKdnaAssetReader = assetReader.createKdnaAssetReader;
@@ -50,3 +53,17 @@ export const deriveLicensedEntryKey = cryptoProfile.deriveLicensedEntryKey;
 export const encryptLicensedEntry = cryptoProfile.encryptLicensedEntry;
 export const decryptLicensedEntry = cryptoProfile.decryptLicensedEntry;
 export const createLicensedDecryptEntry = cryptoProfile.createLicensedDecryptEntry;
+export const EXTERNAL_ENVELOPE_PROFILE = externalKeyGrant.EXTERNAL_ENVELOPE_PROFILE;
+export const EXTERNAL_GRANT_PROFILE = externalKeyGrant.EXTERNAL_GRANT_PROFILE;
+export const KDNAExternalGrantError = externalKeyGrant.KDNAExternalGrantError;
+export const canonicalJson = externalKeyGrant.canonicalJson;
+export const grantSigningPayload = externalKeyGrant.grantSigningPayload;
+export const validateExternalEnvelope = externalKeyGrant.validateExternalEnvelope;
+export const validateExternalKeyGrant = externalKeyGrant.validateExternalKeyGrant;
+export const deriveExternalAssetCek = externalKeyGrant.deriveExternalAssetCek;
+export const encodeExternalEnvelope = externalKeyGrant.encodeExternalEnvelope;
+export const decodeExternalEnvelope = externalKeyGrant.decodeExternalEnvelope;
+export const encryptExternalGrantEntry = externalKeyGrant.encryptExternalGrantEntry;
+export const generateDeviceKeyPairs = externalKeyGrant.generateDeviceKeyPairs;
+export const createExternalKeyGrant = externalKeyGrant.createExternalKeyGrant;
+export const authorizeExternalKeyGrant = externalKeyGrant.authorizeExternalKeyGrant;

package/src/runtime-api.js

@@ -0,0 +1,91 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const v1 = require('./v1');
+
+function invalidDirectoryPlan(inputPath) {
+  const resolved = path.resolve(inputPath);
+  return {
+    kdna_version: null,
+    asset: { asset_id: null, asset_uid: null, title: null, version: null, judgment_version: null },
+    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,
+    },
+    issues: [{
+      code: 'KDNA_ASSET_FILE_REQUIRED',
+      severity: 'blocking',
+      message: 'Runtime loading requires a packaged .kdna asset file. Source directories are authoring inputs only.',
+    }],
+    source: { kind: 'dir', path: resolved },
+  };
+}
+
+function isDirectory(inputPath) {
+  if (typeof inputPath !== 'string') return false;
+  try {
+    return fs.statSync(path.resolve(inputPath)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function guardResolver(options = {}) {
+  if (typeof options.resolveAsset !== 'function') return options;
+  const resolveAsset = options.resolveAsset;
+  return {
+    ...options,
+    resolveAsset(name) {
+      const resolved = resolveAsset(name);
+      if (resolved?.path && isDirectory(resolved.path)) {
+        const error = new Error(
+          `Resolved asset "${name}" is a source directory. Runtime dependencies must be packaged .kdna files.`,
+        );
+        error.code = 'KDNA_ASSET_FILE_REQUIRED';
+        throw error;
+      }
+      return resolved;
+    },
+  };
+}
+
+function planLoad(inputPath, options = {}) {
+  if (isDirectory(inputPath)) return invalidDirectoryPlan(inputPath);
+  return v1.planLoad(inputPath, guardResolver(options));
+}
+
+function loadAuthorized(inputPath, options = {}) {
+  const plan = planLoad(inputPath, options);
+  if (plan.can_load_now !== true) {
+    const issueCodes = Array.isArray(plan.issues)
+      ? plan.issues.map((issue) => issue.code).filter(Boolean)
+      : [];
+    const error = new Error(
+      `LoadPlan denied loading: state=${plan.state || 'invalid'} required_action=${plan.required_action || 'block'}`,
+    );
+    error.code = issueCodes[0] || 'KDNA_LOAD_NOT_AUTHORIZED';
+    error.plan = plan;
+    throw error;
+  }
+  return v1.loadAuthorized(inputPath, guardResolver(options));
+}
+
+module.exports = {
+  planLoad,
+  loadAuthorized,
+  load: loadAuthorized,
+  loadAsset: loadAuthorized,
+};

package/src/types.d.ts

@@ -414,6 +414,165 @@ export function createLicensedDecryptEntry(options: {
   machineFingerprint: string;
 }): NonNullable<KdnaDecryptOptions['decryptEntry']>;
 
+export const EXTERNAL_ENVELOPE_PROFILE: 'kdna-envelope-external-grant-v1';
+export const EXTERNAL_GRANT_PROFILE: 'kdna-key-grant-v1';
+
+export class KDNAExternalGrantError extends Error {
+  code: string;
+}
+
+export interface KDNAExternalGrantEnvelope {
+  profile: 'kdna-envelope-external-grant-v1';
+  alg: 'A256GCM';
+  cek_derivation: 'HKDF-SHA256';
+  key_ref: string;
+  issuer_key_id: string;
+  entry_path: string;
+  plaintext_digest: string;
+  iv: string;
+  tag: string;
+  ciphertext: string;
+}
+
+export interface KDNAExternalKeyGrant {
+  profile: 'kdna-key-grant-v1';
+  grant_id: string;
+  issuer: string;
+  signing_key_id: string;
+  entitlement_id: string;
+  account_id: string;
+  device_id: string;
+  device_public_key: string;
+  device_signing_public_key: string;
+  asset: {
+    asset_id: string;
+    asset_uid: string;
+    version: string;
+    digest: string;
+    entry_path: string;
+    ciphertext_digest: string;
+    key_ref: string;
+    issuer_key_id: string;
+  };
+  issued_at: string;
+  refresh_after: string;
+  offline_grace_until: string;
+  expires_at: string;
+  status: 'active' | 'revoked' | 'expired';
+  status_version: number;
+  wrap: {
+    alg: 'X25519-HKDF-SHA256+A256KW';
+    ephemeral_public_key: string;
+    salt: string;
+    wrapped_cek: string;
+  };
+  signature: string;
+}
+
+export interface KDNADeviceKeyPairs {
+  agreement: { public_key: string; private_key: string };
+  signing: { public_key: string; private_key: string };
+}
+
+/** Runtime-branded by authorizeExternalKeyGrant; a structurally similar object is not accepted. */
+export interface KDNAVerifiedExternalEntitlement {
+  readonly status: 'active' | 'offline_grace';
+  readonly profile: 'kdna-key-grant-v1';
+  readonly grant_id: string;
+  readonly entitlement_id: string;
+  readonly account_id: string;
+  readonly device_id: string;
+  readonly refresh_after: string;
+  readonly offline_grace_until: string;
+  readonly expires_at: string;
+  readonly asset: {
+    readonly asset_id: string;
+    readonly asset_uid: string;
+    readonly version: string;
+    readonly digest: string;
+    readonly entry_path: string;
+    readonly ciphertext_digest: string;
+    readonly key_ref: string;
+    readonly issuer_key_id: string;
+  };
+}
+
+export interface KDNAExternalAuthorization {
+  entitlement: KDNAVerifiedExternalEntitlement;
+  decryptEntry: NonNullable<KdnaDecryptOptions['decryptEntry']>;
+  dispose(): void;
+}
+
+export function canonicalJson(value: unknown): string;
+export function grantSigningPayload(grant: Omit<KDNAExternalKeyGrant, 'signature'> | KDNAExternalKeyGrant): Uint8Array;
+export function validateExternalEnvelope(value: unknown): KDNAExternalGrantEnvelope;
+export function validateExternalKeyGrant(value: unknown): KDNAExternalKeyGrant;
+export function externalEnvelopeAad(options: {
+  manifest: KDNAManifest;
+  entryName: string;
+  plaintextDigest: string;
+  keyRef: string;
+  issuerKeyId: string;
+}): Uint8Array;
+export function deriveExternalAssetCek(options: {
+  issuerRootKey: string | Uint8Array;
+  manifest: KDNAManifest;
+  entryName: string;
+  plaintextDigest: string;
+  keyRef: string;
+  issuerKeyId: string;
+}): Uint8Array;
+export function encodeExternalEnvelope(value: KDNAExternalGrantEnvelope): Uint8Array;
+export function decodeExternalEnvelope(value: KDNAExternalGrantEnvelope | Uint8Array): KDNAExternalGrantEnvelope;
+export function encryptExternalGrantEntry(plaintext: string | Uint8Array, options: {
+  manifest: KDNAManifest;
+  entryName?: string;
+  issuerRootKey: string | Uint8Array;
+  keyRef: string;
+  issuerKeyId: string;
+  iv?: Uint8Array;
+}): KDNAExternalGrantEnvelope;
+export function generateDeviceKeyPairs(): KDNADeviceKeyPairs;
+export function createExternalKeyGrant(options: {
+  issuerRootKey: string | Uint8Array;
+  issuerSigningPrivateKey: unknown;
+  signingKeyId: string;
+  issuer: string;
+  entitlementId: string;
+  accountId: string;
+  deviceId: string;
+  devicePublicKey: string;
+  deviceSigningPublicKey: string;
+  manifest: KDNAManifest;
+  envelope: KDNAExternalGrantEnvelope | Uint8Array;
+  assetDigest: string;
+  status?: 'active' | 'revoked' | 'expired';
+  statusVersion?: number;
+  issuedAt?: Date | string;
+  refreshAfter?: Date | string;
+  offlineGraceUntil?: Date | string;
+  expiresAt?: Date | string;
+  grantId?: string;
+  ephemeralKeyPair?: unknown;
+  wrapSalt?: Uint8Array;
+}): KDNAExternalKeyGrant;
+export function authorizeExternalKeyGrant(options: {
+  grant: KDNAExternalKeyGrant;
+  issuerPublicKeys: Map<string, unknown> | Record<string, unknown>;
+  manifest: KDNAManifest;
+  checksums: KDNAChecksums;
+  envelope: KDNAExternalGrantEnvelope | Uint8Array;
+  deviceAgreementKey: KDNADeviceKeyPairs['agreement'] | unknown;
+  expectedAccountId: string;
+  expectedDeviceId: string;
+  expectedDeviceSigningPublicKey: string;
+  minimumStatusVersion?: number;
+  now?: Date | string;
+  networkAvailable?: boolean;
+  allowOffline?: boolean;
+}): KDNAExternalAuthorization;
+export function isVerifiedExternalEntitlement(value: unknown): value is KDNAVerifiedExternalEntitlement;
+
 // Stable public API — preferred entry points for third-party integrations.
 export type KDNAAssetInput = string | Uint8Array | KdnaAsset;
 
@@ -482,7 +641,7 @@ export function matchDomain(input: string, candidates: Array<KDNAAssetInput | KD
 export function matchDomainSync(input: string, candidates: Array<KDNAAssetInput | KDNAInspectResult>, options?: KdnaDecryptOptions): KDNAMatchResult[];
 export function composeKDNA(inputs: KDNAAssetInput[], options?: { input?: string; profile?: 'compact' | 'scenario' | 'full' | string; separator?: string } & KdnaDecryptOptions): Promise<KDNAComposeResult>;
 
-// KDNA Core — source directory / container API
+// KDNA Core — authoring source and packaged runtime API
 export const MIMETYPE: string;
 export const REQUIRED_DIR_ENTRIES: string[];
 
@@ -553,7 +712,7 @@ export interface KDNALoadPlan {
     path: string;
   };
 }
-export function planLoad(inputPath: string, options?: { password?: string; hasPassword?: boolean; entitlement?: Record<string, any> }): KDNALoadPlan;
+export function planLoad(inputPath: string, options?: { password?: string; hasPassword?: boolean; entitlement?: KDNAVerifiedExternalEntitlement | Record<string, any> }): KDNALoadPlan;
 export function buildChecksums(sourceDir: string): KDNAChecksums;
 export function pack(sourceDir: string, outputPath: string): void;
 export function unpack(inputPath: string, outputDir: string): void;

package/src/v1/index.js

@@ -1,17 +1,15 @@
 /**
- * v1-cli.js — KDNA Core v1 inspect / validate / pack / unpack for the
- * kdna monorepo CLI shim.
+ * KDNA Asset Container inspect / validate / pack / unpack implementation.
  *
  * KDNA Core is the official KDNA judgment-asset format and runtime
  * loading contract. .kdna assets are created, inspected, packed,
  * unpacked, and validated through the official KDNA toolchain. This
- * module is the v1 component of that toolchain.
  *
- * The KDNA Core v1 file format is documented in docs/core/file-format.md.
+ * The KDNA Asset Container is documented in docs/core/file-format.md.
  * This module is the shared implementation that:
  *
- *   - packages/kdna/bin/kdna.js uses as a v1-aware router
- *   - scripts/v1-*.mjs delegate to (via child_process) so the legacy
+ *   - packages/kdna/bin/kdna.js uses as its container router
+ *   - compatibility scripts delegate to it so historical tooling
  *     scripts and the official CLI cannot drift
  *
  * Hard rules from the format spec:
@@ -39,6 +37,11 @@ const path = require('node:path');
 const zlib = require('node:zlib');
 const crypto = require('node:crypto');
 const cbor = require('cbor-x');
+const {
+  EXTERNAL_ENVELOPE_PROFILE,
+  validateExternalEnvelope,
+  isVerifiedExternalEntitlement,
+} = require('../external-key-grant');
 
 const { readAsset } = (() => {
   try {
@@ -178,7 +181,7 @@ function loadSchemas() {
 // ─── Format detection ──────────────────────────────────────────────────
 
 /**
- * Detect whether a directory is a v1 source layout.
+ * Detect whether a directory is a KDNA authoring source layout.
  * Required entries: mimetype, kdna.json, payload.kdnab.
  * mimetype content must equal "application/vnd.kdna.asset".
  */
@@ -536,10 +539,10 @@ function readV1Layout(absPath) {
     for (const f of V1_REQUIRED_DIR_ENTRIES) {
       const full = path.join(absPath, f);
       if (!fs.existsSync(full)) {
-        throw new Error(`not a KDNA v1 source dir: missing ${f}`);
+        throw new Error(`not a KDNA authoring source directory: missing ${f}`);
       }
       if (fs.lstatSync(full).isSymbolicLink()) {
-        throw new Error(`not a KDNA v1 source dir: ${f} must not be a symlink`);
+        throw new Error(`not a KDNA authoring source directory: ${f} must not be a symlink`);
       }
     }
     for (const f of [...V1_REQUIRED_DIR_ENTRIES, ...V1_OPTIONAL_DIR_ENTRIES]) {
@@ -557,10 +560,10 @@ function readV1Layout(absPath) {
     kind = 'file';
     entries = listZipEntries(absPath);
     if (entries.length === 0 || entries[0].name !== 'mimetype') {
-      throw new Error('not a KDNA v1 container: first entry is not mimetype');
+      throw new Error('not a KDNA Asset Container: first entry is not mimetype');
     }
     if (entries[0].method !== 0) {
-      throw new Error('not a KDNA v1 container: mimetype must be uncompressed');
+      throw new Error('not a KDNA Asset Container: mimetype must be uncompressed');
     }
     for (const e of entries) {
       // We only need the well-known entries; signatures/ attachments/ etc.
@@ -576,7 +579,7 @@ function readV1Layout(absPath) {
     }
     for (const f of V1_REQUIRED_DIR_ENTRIES) {
       if (!map[f]) {
-        throw new Error(`not a KDNA v1 container: missing ${f}`);
+        throw new Error(`not a KDNA Asset Container: missing ${f}`);
       }
     }
   } else {
@@ -725,7 +728,7 @@ function runValidate(v1) {
   if (!validators) {
     result.schema_valid = false;
     problems.push(
-      'schema: ajv not available. KDNA Core v1 requires ajv and ajv-formats for JSON-Schema validation. Run: npm install ajv ajv-formats (or: npm install -g ajv ajv-formats for global CLI users)',
+      'schema: KDNA Core requires ajv and ajv-formats for JSON-Schema validation. Run: npm install ajv ajv-formats (or: npm install -g ajv ajv-formats for global CLI users)',
     );
     return finalizeValidate(result, problems);
   }
@@ -758,7 +761,16 @@ function runValidate(v1) {
       result.payload_valid = false;
       problems.push(`payload: encrypted envelope profile ${payload.profile || 'unknown'} does not match manifest encryption profile ${encProfile}`);
     }
-    const hasKeyMaterial = !!payload.wrapped_key || (Array.isArray(payload.key_slots) && payload.key_slots.length > 0);
+    let hasKeyMaterial = !!payload.wrapped_key || (Array.isArray(payload.key_slots) && payload.key_slots.length > 0);
+    if (payload.profile === EXTERNAL_ENVELOPE_PROFILE) {
+      try {
+        validateExternalEnvelope(payload);
+        hasKeyMaterial = true;
+      } catch (error) {
+        result.payload_valid = false;
+        problems.push(`payload: ${error.message}`);
+      }
+    }
     if (!payload.profile || !payload.ciphertext || !hasKeyMaterial) {
       result.payload_valid = false;
       problems.push('payload: encrypted envelope missing required fields (profile/ciphertext/key material)');
@@ -919,7 +931,7 @@ function buildChecksumsV1(sourceDir) {
 // ─── pack ──────────────────────────────────────────────────────────────
 
 /**
- * Pack a v1 source directory into a .kdna container. Output is
+ * Pack an authoring source directory into a .kdna asset. Output is
  * deterministic: the same source directory packed twice produces
  * byte-identical output (fixed DOS timestamps, fixed entry order,
  * mimetype first).
@@ -1017,7 +1029,7 @@ function unpack(inputPath, outputDir) {
     throw new Error(`not a file: ${absIn}`);
   }
   const entries = listZipEntries(absIn);
-  // Sanity: v1 container must have mimetype as first entry with the v1 media type.
+  // Sanity: the asset must have mimetype as its first, uncompressed entry.
   if (entries.length === 0 || entries[0].name !== 'mimetype') {
     throw new Error('not a KDNA container: first entry is not mimetype');
   }
@@ -1101,12 +1113,11 @@ function finalizeLoadPlan(plan) {
   return plan;
 }
 
-function computeSourceFingerprint(inputPath, v1) {
-  const absPath = path.resolve(inputPath);
-  if (v1.kind === 'file') {
-    return `sha256:${crypto.createHash('sha256').update(fs.readFileSync(absPath)).digest('hex')}`;
-  }
-
+function computeSourceFingerprint(_inputPath, v1) {
+  // Fingerprint the logical entries, not the transport ZIP bytes. DEFLATE
+  // output can differ between zlib versions and operating systems even when
+  // every uncompressed KDNA entry is identical. LoadPlan conformance must be
+  // stable across JS, Swift, CI runners, and repackaging transports.
   const hash = crypto.createHash('sha256');
   for (const name of Object.keys(v1.map).sort()) {
     const bytes = v1.map[name];
@@ -1211,14 +1222,15 @@ function canonicalToV1Layout(asset) {
 }
 
 /**
- * Plan a KDNA v1 runtime load without decrypting or emitting judgment content.
+ * Plan a KDNA runtime load without decrypting or emitting judgment content.
  * Product consumers such as Chat should render authorization UI from this
  * result instead of parsing manifest fields directly.
  */
 function planLoad(inputPath, opts = {}) {
   let v1;
 
-  // Try the unified container dispatcher first (handles v1 dirs, v1 containers, v2 containers)
+  // Try the unified container dispatcher first; the internal compatibility
+  // reader below remains available only for authoring and migration tooling.
   if (readAsset !== null) {
     try {
       const asset = readAsset(path.resolve(inputPath));
@@ -1278,6 +1290,36 @@ function planLoad(inputPath, opts = {}) {
 
   const manifest = v1.manifest;
 
+  function externalEntitlementMatchesCurrentAsset(entitlement) {
+    if (!isVerifiedExternalEntitlement(entitlement) || !entitlement.asset) return false;
+    let checksums;
+    try {
+      checksums = v1.map['checksums.json']
+        ? parseJsonEntry('checksums.json', v1.map['checksums.json'])
+        : null;
+    } catch {
+      return false;
+    }
+    return entitlement.asset.asset_id === (manifest.asset_id || manifest.name)
+      && entitlement.asset.asset_uid === manifest.asset_uid
+      && entitlement.asset.version === manifest.version
+      && entitlement.asset.digest === checksums?.asset_digest
+      && entitlement.asset.entry_path === manifest.payload?.path;
+  }
+
+  function rejectExternalEntitlementMismatch() {
+    plan.state = 'invalid';
+    plan.required_action = 'block';
+    plan.can_load_now = false;
+    plan.projection_policy = 'none';
+    plan.issues.push(buildLoadPlanIssue(
+      'KDNA_GRANT_ASSET_MISMATCH',
+      'blocking',
+      'The verified account/device grant is bound to a different asset, version, digest, or encrypted entry.',
+    ));
+    return finalizeLoadPlan(plan);
+  }
+
   // Resolve dependencies if declared (Story 6)
   const resolvedDeps = [];
   if (manifest.dependencies && typeof manifest.dependencies === 'object' && Object.keys(manifest.dependencies).length > 0) {
@@ -1449,6 +1491,23 @@ function planLoad(inputPath, opts = {}) {
     }
 
     if (plan.entitlement_profile === 'account') {
+      if (isVerifiedExternalEntitlement(opts.entitlement)) {
+        if (!externalEntitlementMatchesCurrentAsset(opts.entitlement)) {
+          return rejectExternalEntitlementMismatch();
+        }
+        plan.state = opts.entitlement.status === 'offline_grace' ? 'offline_grace' : 'ready';
+        plan.required_action = opts.entitlement.status === 'offline_grace' ? 'sync' : 'load';
+        plan.can_load_now = true;
+        plan.projection_policy = 'minimal';
+        if (opts.entitlement.status === 'offline_grace') {
+          plan.issues.push(buildLoadPlanIssue(
+            'KDNA_AUTH_OFFLINE_GRACE_ACTIVE',
+            'warning',
+            'The verified device grant can load offline but must sync before grace expires.',
+          ));
+        }
+        return finalizeLoadPlan(plan);
+      }
       plan.state = 'needs_account';
       plan.required_action = 'sign_in_or_activate';
       plan.can_load_now = false;
@@ -1462,6 +1521,16 @@ function planLoad(inputPath, opts = {}) {
     }
 
     if (plan.entitlement_profile === 'org') {
+      if (isVerifiedExternalEntitlement(opts.entitlement)) {
+        if (!externalEntitlementMatchesCurrentAsset(opts.entitlement)) {
+          return rejectExternalEntitlementMismatch();
+        }
+        plan.state = opts.entitlement.status === 'offline_grace' ? 'offline_grace' : 'ready';
+        plan.required_action = opts.entitlement.status === 'offline_grace' ? 'sync' : 'load';
+        plan.can_load_now = true;
+        plan.projection_policy = 'minimal';
+        return finalizeLoadPlan(plan);
+      }
       plan.state = 'needs_org_auth';
       plan.required_action = 'sign_in_or_activate';
       plan.can_load_now = false;
@@ -1828,7 +1897,7 @@ function loadV1Unsafe(inputPath, opts = {}) {
         payload = parsePayloadEntry('payload.kdnab', decryptedBuf);
       } catch (e) {
         const err = new Error(`Decryption failed: ${e.message}`);
-        err.code = 'KDNA_DECRYPT_FAILED';
+        err.code = e.code || 'KDNA_DECRYPT_FAILED';
         throw err;
       }
     } else if (opts.password) {
@@ -1859,8 +1928,13 @@ function loadV1Unsafe(inputPath, opts = {}) {
         throw err;
       }
     } else {
-      const err = new Error('payload is encrypted and cannot be decrypted without a password or license key');
-      err.code = 'KDNA_AUTH_PASSWORD_REQUIRED';
+      const isExternal = payload.profile === EXTERNAL_ENVELOPE_PROFILE;
+      const err = new Error(
+        isExternal
+          ? 'payload requires a verified account/device external key grant'
+          : 'payload is encrypted and cannot be decrypted without an authorized credential',
+      );
+      err.code = isExternal ? 'KDNA_AUTH_ACCOUNT_REQUIRED' : 'KDNA_AUTH_PASSWORD_REQUIRED';
       throw err;
     }
   }
@@ -1891,7 +1965,7 @@ function loadV1Unsafe(inputPath, opts = {}) {
     const hasJudgment = (core.axioms && core.axioms.length > 0)
       || (core.boundaries && core.boundaries.length > 0)
       || (payload.patterns && payload.patterns.length > 0)
-      || (payload.reasoning && ((payload.reasoning.self_checks && payload.reasoning.self_checks.length > 0) || (payload.reasoning.failure_modes && payload.reasoning.failure_modes.length > 0)));
+      || (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');
     if (payload.scenarios && payload.scenarios.length > 0) profiles.push('scenario');
@@ -1926,7 +2000,11 @@ function loadV1Unsafe(inputPath, opts = {}) {
       highest_question: core.highest_question || null,
       axioms: (core.axioms || []).map(normalizeCompactAxiom).filter(Boolean),
       boundaries: normalizeList(core.boundaries),
-      self_checks: normalizeList(payload.reasoning && payload.reasoning.self_checks),
+      // The canonical payload field is singular (`reasoning.self_check`).
+      // Runtime Capsule uses plural (`context.self_checks`) as its projection
+      // field. Reading the plural name from the payload silently discarded
+      // every Studio-authored self-check.
+      self_checks: normalizeList(payload.reasoning && payload.reasoning.self_check),
       failure_modes: normalizeList(payload.reasoning && payload.reasoning.failure_modes),
       patterns: normalizeList(payload.patterns).slice(0, 3),
     };