@aarmos/avar-core 1.0.0 → 1.1.0

package/dist/index.d.ts

@@ -194,4 +194,80 @@ declare function signedBodyOf(entry: AvarEntry): Omit<AvarEntry, "signature" | "
 
 declare function verifyBundle(bundle: AvarBundle): Promise<VerificationReport>;
 
-export { type AvarBundle, type AvarEntry, type BundleManifest, type BundlePubKeys, type DecisionStep, GENESIS_PREV_HASH, GENESIS_PREV_STEP_HASH, type PolicyHit, type TextStep, type ToolStep, type TraceStep, type VerificationIssue, type VerificationReport, canonicalize, computeDeviceFingerprint, computeEntryHash, computeStepHash, sha256Hex, signedBodyOf, utf8, verifyBundle, verifySignature };
+type DiffOp = {
+    op: "add";
+    path: string;
+    value: unknown;
+} | {
+    op: "remove";
+    path: string;
+    oldValue: unknown;
+} | {
+    op: "replace";
+    path: string;
+    oldValue: unknown;
+    value: unknown;
+};
+type CanonicalDiff = {
+    equal: boolean;
+    ops: DiffOp[];
+};
+/** Structural, canonical diff of two JSON values. */
+declare function diffCanonical(a: unknown, b: unknown): CanonicalDiff;
+type ReceiptEntryChange = {
+    id: string;
+    indexA: number;
+    indexB: number;
+    ops: DiffOp[];
+    signatureChanged: boolean;
+    entryHashChanged: boolean;
+    stepsChanged: boolean;
+};
+type ReceiptDiff = {
+    equal: boolean;
+    kind: "bundle" | "entry";
+    specVersion: {
+        from: string;
+        to: string;
+    } | null;
+    chainHead: {
+        from: {
+            entryHash: string;
+            index: number;
+        };
+        to: {
+            entryHash: string;
+            index: number;
+        };
+        extended: boolean;
+    } | null;
+    devicePublicKeys: {
+        added: string[];
+        removed: string[];
+    };
+    entries: {
+        added: Array<{
+            id: string;
+            index: number;
+        }>;
+        removed: Array<{
+            id: string;
+            index: number;
+        }>;
+        modified: ReceiptEntryChange[];
+        unchanged: number;
+    };
+    /** Raw canonical diff of manifest + pubkeys (entries handled above). */
+    ops: DiffOp[];
+};
+/**
+ * Compare two AVAR receipts. Accepts full bundles OR single entries.
+ * Entries are matched by `id`, not by index — reordering is not a diff.
+ */
+declare function diffReceipts(a: unknown, b: unknown): ReceiptDiff;
+/** Canonical diff of two policy documents. Schema-agnostic. */
+declare function diffPolicies(a: unknown, b: unknown): CanonicalDiff;
+/** Canonical diff of two tool manifests. Schema-agnostic. */
+declare function diffToolManifests(a: unknown, b: unknown): CanonicalDiff;
+
+export { type AvarBundle, type AvarEntry, type BundleManifest, type BundlePubKeys, type CanonicalDiff, type DecisionStep, type DiffOp, GENESIS_PREV_HASH, GENESIS_PREV_STEP_HASH, type PolicyHit, type ReceiptDiff, type ReceiptEntryChange, type TextStep, type ToolStep, type TraceStep, type VerificationIssue, type VerificationReport, canonicalize, computeDeviceFingerprint, computeEntryHash, computeStepHash, diffCanonical, diffPolicies, diffReceipts, diffToolManifests, sha256Hex, signedBodyOf, utf8, verifyBundle, verifySignature };

package/dist/index.js

@@ -294,6 +294,165 @@ function computeChainHead(entries) {
   }
   return { entryHash: "", index: -1 };
 }
+
+// src/diff.ts
+function isPlainObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function escapePointer(seg) {
+  return seg.replace(/~/g, "~0").replace(/\//g, "~1");
+}
+function join(base, seg) {
+  return `${base}/${typeof seg === "number" ? seg : escapePointer(seg)}`;
+}
+function diffCanonical(a, b) {
+  const ops = [];
+  walk(a, b, "", ops);
+  return { equal: ops.length === 0, ops };
+}
+function walk(a, b, path, ops) {
+  if (a === b) return;
+  if ((a === null || typeof a !== "object") && (b === null || typeof b !== "object")) {
+    if (canonicalize(a) !== canonicalize(b)) {
+      ops.push({ op: "replace", path: path || "/", oldValue: a, value: b });
+    }
+    return;
+  }
+  if (Array.isArray(a) && Array.isArray(b)) {
+    const min = Math.min(a.length, b.length);
+    for (let i = 0; i < min; i++) walk(a[i], b[i], join(path, i), ops);
+    if (b.length > a.length) {
+      for (let i = a.length; i < b.length; i++) {
+        ops.push({ op: "add", path: join(path, i), value: b[i] });
+      }
+    } else if (a.length > b.length) {
+      for (let i = b.length; i < a.length; i++) {
+        ops.push({ op: "remove", path: join(path, i), oldValue: a[i] });
+      }
+    }
+    return;
+  }
+  if (isPlainObject(a) && isPlainObject(b)) {
+    const keys = /* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)]);
+    const sorted = [...keys].sort();
+    for (const k of sorted) {
+      const inA = Object.prototype.hasOwnProperty.call(a, k);
+      const inB = Object.prototype.hasOwnProperty.call(b, k);
+      if (inA && !inB) ops.push({ op: "remove", path: join(path, k), oldValue: a[k] });
+      else if (!inA && inB) ops.push({ op: "add", path: join(path, k), value: b[k] });
+      else walk(a[k], b[k], join(path, k), ops);
+    }
+    return;
+  }
+  ops.push({ op: "replace", path: path || "/", oldValue: a, value: b });
+}
+function isBundle(v) {
+  return isPlainObject(v) && typeof v.specVersion === "string" && isPlainObject(v.manifest) && Array.isArray(v.entries);
+}
+function isEntry(v) {
+  return isPlainObject(v) && typeof v.id === "string" && Array.isArray(v.steps);
+}
+function diffEntryPair(a, b, indexA, indexB) {
+  const { entriesNdjsonBytes: _skip1, ...aClean } = a;
+  const { entriesNdjsonBytes: _skip2, ...bClean } = b;
+  void _skip1;
+  void _skip2;
+  const { ops } = diffCanonical(aClean, bClean);
+  const signatureChanged = ops.some((o) => o.path === "/signature" || o.path.startsWith("/signature/"));
+  const entryHashChanged = ops.some((o) => o.path === "/entryHash");
+  const stepsChanged = ops.some((o) => o.path === "/steps" || o.path.startsWith("/steps/"));
+  return {
+    id: a.id,
+    indexA,
+    indexB,
+    ops,
+    signatureChanged,
+    entryHashChanged,
+    stepsChanged
+  };
+}
+function diffReceipts(a, b) {
+  if (isEntry(a) && isEntry(b)) {
+    const change = diffEntryPair(a, b, 0, 0);
+    return {
+      equal: change.ops.length === 0,
+      kind: "entry",
+      specVersion: null,
+      chainHead: null,
+      devicePublicKeys: { added: [], removed: [] },
+      entries: {
+        added: [],
+        removed: [],
+        modified: change.ops.length === 0 ? [] : [change],
+        unchanged: change.ops.length === 0 ? 1 : 0
+      },
+      ops: change.ops
+    };
+  }
+  if (!isBundle(a) || !isBundle(b)) {
+    throw new Error("diffReceipts: inputs must be AvarBundle or AvarEntry values.");
+  }
+  const specVersion = a.specVersion === b.specVersion ? null : { from: a.specVersion, to: b.specVersion };
+  const headA = a.manifest.chainHead;
+  const headB = b.manifest.chainHead;
+  const chainHead = headA.entryHash === headB.entryHash && headA.index === headB.index ? null : {
+    from: headA,
+    to: headB,
+    extended: headB.index > headA.index
+  };
+  const keysA = new Set(a.manifest.devicePublicKeys ?? []);
+  const keysB = new Set(b.manifest.devicePublicKeys ?? []);
+  const devicePublicKeys = {
+    added: [...keysB].filter((k) => !keysA.has(k)).sort(),
+    removed: [...keysA].filter((k) => !keysB.has(k)).sort()
+  };
+  const byIdA = /* @__PURE__ */ new Map();
+  a.entries.forEach((e, i) => byIdA.set(e.id, { entry: e, index: i }));
+  const byIdB = /* @__PURE__ */ new Map();
+  b.entries.forEach((e, i) => byIdB.set(e.id, { entry: e, index: i }));
+  const added = [];
+  const removed = [];
+  const modified = [];
+  let unchanged = 0;
+  for (const [id, { entry, index }] of byIdB) {
+    const prior = byIdA.get(id);
+    if (!prior) {
+      added.push({ id, index });
+      continue;
+    }
+    const change = diffEntryPair(prior.entry, entry, prior.index, index);
+    if (change.ops.length === 0) unchanged++;
+    else modified.push(change);
+  }
+  for (const [id, { index }] of byIdA) {
+    if (!byIdB.has(id)) removed.push({ id, index });
+  }
+  added.sort((x, y) => x.index - y.index);
+  removed.sort((x, y) => x.index - y.index);
+  modified.sort((x, y) => x.indexA - y.indexA);
+  const strip = (bundle) => ({
+    specVersion: bundle.specVersion,
+    manifest: bundle.manifest,
+    pubkeys: bundle.pubkeys
+  });
+  const headerDiff = diffCanonical(strip(a), strip(b));
+  const equal = added.length === 0 && removed.length === 0 && modified.length === 0 && headerDiff.equal;
+  return {
+    equal,
+    kind: "bundle",
+    specVersion,
+    chainHead,
+    devicePublicKeys,
+    entries: { added, removed, modified, unchanged },
+    ops: headerDiff.ops
+  };
+}
+function diffPolicies(a, b) {
+  return diffCanonical(a, b);
+}
+function diffToolManifests(a, b) {
+  return diffCanonical(a, b);
+}
 export {
   GENESIS_PREV_HASH,
   GENESIS_PREV_STEP_HASH,
@@ -301,6 +460,10 @@ export {
   computeDeviceFingerprint,
   computeEntryHash,
   computeStepHash,
+  diffCanonical,
+  diffPolicies,
+  diffReceipts,
+  diffToolManifests,
   sha256Hex,
   signedBodyOf,
   utf8,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aarmos/avar-core",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Reference implementation of the AVAR (Aarmos Verifiable Action Record) spec — canonical JSON, Ed25519 signature verification, hash-chain math, and bundle verification. Pure, zero-dep, browser + Node.",
   "type": "module",
   "main": "./dist/index.js",