@aikdna/kdna-core 0.15.11 → 0.16.0

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

@@ -203,9 +203,7 @@ export interface KDNAFileDataMap {
 }
 
 export interface KDNAManifest {
-  format: 'kdna';
-  format_version: '2.0';
-  spec_version: string;
+  kdna_version: '1.0';
   name: string;
   version: string;
   judgment_version: string;
@@ -416,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;
 
@@ -484,36 +641,33 @@ 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 v1 — source directory / container API
+// KDNA Core — authoring source and packaged runtime API
 export const MIMETYPE: string;
-export const MIMETYPE_V1: string;
-export const MIMETYPE_V2: string;
-export const V1_REQUIRED_DIR_ENTRIES: string[];
+export const REQUIRED_DIR_ENTRIES: string[];
 
-export interface KDNAV1ChecksumEntry {
+export interface KDNAChecksumEntry {
   algorithm: 'sha256';
   value: string;
 }
 
-export interface KDNAV1Checksums {
+export interface KDNAChecksums {
   algorithm: 'sha256';
   manifest_digest: string;
   payload_digest: string;
   asset_digest: string;
-  entries: Record<string, KDNAV1ChecksumEntry>;
+  entries: Record<string, KDNAChecksumEntry>;
 }
 
-export function isV1SourceDir(inputPath: string): boolean;
-export function isV2SourceDir(inputPath: string): boolean;
-export function detectContainerFormat(inputPath: string): 'v1' | 'v2' | null;
+export function isKdnaSourceDir(inputPath: string): boolean;
+export function detectContainerFormat(inputPath: string): 'kdna' | null;
 export function inspect(inputPath: string, options?: Record<string, any>): Record<string, any>;
 export function validate(inputPath: string, options?: Record<string, any>): Record<string, any>;
-export interface KDNAV1LoadPlanIssue {
+export interface KDNALoadPlanIssue {
   code: string;
   severity: 'info' | 'warning' | 'blocking' | string;
   message: string;
 }
-export interface KDNAV1LoadPlan {
+export interface KDNALoadPlan {
   kdna_version: string | null;
   asset: {
     asset_id: string | null;
@@ -552,18 +706,19 @@ export interface KDNAV1LoadPlan {
   projection_policy: 'minimal' | 'remote' | 'none' | string;
   input_fingerprint: string | null;
   checks: Record<string, boolean>;
-  issues: KDNAV1LoadPlanIssue[];
+  issues: KDNALoadPlanIssue[];
   source: {
     kind: 'dir' | 'file' | string | null;
     path: string;
   };
 }
-export function planLoad(inputPath: string, options?: { password?: string; hasPassword?: boolean; entitlement?: Record<string, any> }): KDNAV1LoadPlan;
-export function buildChecksumsV1(sourceDir: string): KDNAV1Checksums;
+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;
 export function loadAuthorized(inputPath: string, options?: { profile?: 'index' | 'compact' | 'scenario' | 'full' | string; as?: 'json' | 'prompt' | string }): Record<string, any>;
-export function loadV1(inputPath: string, options?: { profile?: 'index' | 'compact' | 'scenario' | 'full' | string; as?: 'json' | 'prompt' | string }): Record<string, any>;
+export function load(inputPath: string, options?: { profile?: 'index' | 'compact' | 'scenario' | 'full' | string; as?: 'json' | 'prompt' | string }): Record<string, any>;
+export function loadAsset(inputPath: string, options?: { profile?: 'index' | 'compact' | 'scenario' | 'full' | string; as?: 'json' | 'prompt' | string }): Record<string, any>;
 export const FORBIDDEN_OUTPUT_TERMS: readonly string[];
 
 // Lint