@aarmos/avar-core 1.0.0 → 1.2.0

package/README.md

@@ -53,4 +53,4 @@ Apache-2.0. See [`LICENSE`](./LICENSE) and [`NOTICE`](./NOTICE).
 
 ## Spec revision
 
-Tracks `avar/1` spec revision `1.0`. See the [AVAR spec](https://github.com/Aarmatix/avar-spec/blob/main/SPEC.md) for the current revision and changelog.
+Tracks `avar/1` spec revision `1.1` (release candidate; backward-compatible with `1.0-rc1`). See the [AVAR spec](https://github.com/Aarmatix/avar-spec/blob/main/SPEC.md) for the current revision and changelog.

package/dist/index.d.ts

@@ -194,4 +194,43 @@ 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 AarmosErrorCode = "BUNDLE_OVERSIZED" | "BUNDLE_NOT_ZIP" | "BUNDLE_MISSING_FILES" | "BUNDLE_INVALID_JSON" | "BUNDLE_INVALID_NDJSON" | "BUNDLE_SPEC_UNSUPPORTED" | "BUNDLE_EMPTY" | "SPEC_VERSION_MISMATCH" | "ENTRIES_SHA256_MISMATCH" | "SIGNATURE_MISMATCH" | "FINGERPRINT_MISMATCH" | "CHAIN_BROKEN" | "STEP_CHAIN_BROKEN" | "MANIFEST_INVALID" | "FILE_NOT_FOUND" | "FILE_UNREADABLE" | "UNKNOWN";
+interface AarmosError {
+    code: AarmosErrorCode;
+    message: string;
+    hint: string;
+    docsUrl: string;
+}
+declare const AARMOS_ERROR_TEMPLATES: Record<AarmosErrorCode, Omit<AarmosError, "code">>;
+declare function aarmosError(code: AarmosErrorCode, overrides?: Partial<Omit<AarmosError, "code">>): AarmosError;
+/** One-line human-readable format used by the CLI on stderr / bridge diagnostics. */
+declare function formatAarmosErrorLine(err: AarmosError): string;
+/**
+ * Report-level classifier. Given an invalid VerificationReport, return the
+ * single most-important AarmosError to surface. Priority reflects severity:
+ * envelope > signature > fingerprint > chain > step-chain > format.
+ */
+declare function classifyReport(report: {
+    formatOk: boolean;
+    entriesSha256Ok: boolean;
+    signaturesOk: boolean;
+    fingerprintsOk: boolean;
+    chainOk: boolean;
+    perStepChainOk: boolean;
+    verdict: "valid" | "invalid" | "valid-with-warnings";
+    issues: {
+        kind: string;
+        detail?: string;
+    }[];
+}): AarmosError | null;
+/**
+ * Optional Error subclass so throw/catch sites can propagate an AarmosError
+ * through code that expects `Error`. Consumers can detect via
+ * `err instanceof AarmosErrorException` or `err && (err as any).aarmos`.
+ */
+declare class AarmosErrorException extends Error {
+    readonly aarmos: AarmosError;
+    constructor(err: AarmosError);
+}
+
+export { AARMOS_ERROR_TEMPLATES, type AarmosError, type AarmosErrorCode, AarmosErrorException, 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, aarmosError, canonicalize, classifyReport, computeDeviceFingerprint, computeEntryHash, computeStepHash, formatAarmosErrorLine, sha256Hex, signedBodyOf, utf8, verifyBundle, verifySignature };

package/dist/index.js

@@ -294,13 +294,313 @@ function computeChainHead(entries) {
   }
   return { entryHash: "", index: -1 };
 }
+
+// src/errors.ts
+var SPEC_URL = "https://aarmos.io/docs/avar-spec";
+var VERIFY_URL = "https://aarmos.io/trust/verify";
+var QUICKSTART_URL = "https://aarmos.io/docs/quickstart";
+var AARMOS_ERROR_TEMPLATES = {
+  BUNDLE_OVERSIZED: {
+    message: "That bundle is larger than the 25 MB browser limit.",
+    hint: "Run `aarmos verify <bundle>` locally instead \u2014 the CLI has no size cap.",
+    docsUrl: QUICKSTART_URL
+  },
+  BUNDLE_NOT_ZIP: {
+    message: "That file is not a valid .avar.zip.",
+    hint: "Bundles are zip archives. Rename or re-export the file, then try again.",
+    docsUrl: SPEC_URL
+  },
+  BUNDLE_MISSING_FILES: {
+    message: "Bundle is missing one or more required files.",
+    hint: "A valid AVAR bundle contains SPEC-VERSION, manifest.json, entries.ndjson, and pubkeys.json.",
+    docsUrl: SPEC_URL
+  },
+  BUNDLE_INVALID_JSON: {
+    message: "manifest.json or pubkeys.json is not valid JSON.",
+    hint: "The file exists but cannot be parsed. Re-export from the CLI to regenerate a clean bundle.",
+    docsUrl: SPEC_URL
+  },
+  BUNDLE_INVALID_NDJSON: {
+    message: "entries.ndjson contains a malformed line.",
+    hint: "Each line must be a self-contained JSON entry. One corrupt line usually means the file was edited by hand.",
+    docsUrl: SPEC_URL
+  },
+  BUNDLE_SPEC_UNSUPPORTED: {
+    message: "This bundle was produced by a spec version this verifier does not support.",
+    hint: "Update to the latest verifier (`npm i -g @aarmos/avar-core`) or re-export with a matching spec version.",
+    docsUrl: SPEC_URL
+  },
+  BUNDLE_EMPTY: {
+    message: "Bundle contains no entries.",
+    hint: "An empty ledger is unusual \u2014 check that the run actually produced receipts before exporting.",
+    docsUrl: SPEC_URL
+  },
+  SPEC_VERSION_MISMATCH: {
+    message: "This bundle uses a spec version this verifier does not recognize.",
+    hint: "Update the verifier (`npm i -g @aarmos/avar-core`) or re-export the bundle with matching spec version.",
+    docsUrl: SPEC_URL
+  },
+  ENTRIES_SHA256_MISMATCH: {
+    message: "entries.ndjson has been modified since the bundle was signed.",
+    hint: "The envelope hash in manifest.json no longer matches the file. Do not trust this bundle \u2014 re-export from the CLI.",
+    docsUrl: VERIFY_URL
+  },
+  SIGNATURE_MISMATCH: {
+    message: "One or more entry signatures do not match the embedded public keys.",
+    hint: "The bundle was modified after signing, or the wrong pubkeys.json is bundled.",
+    docsUrl: VERIFY_URL
+  },
+  FINGERPRINT_MISMATCH: {
+    message: "Device fingerprint on one or more entries does not match its public key.",
+    hint: "The entry claims a device whose public key does not hash to the declared fingerprint. Treat this bundle as untrusted.",
+    docsUrl: VERIFY_URL
+  },
+  CHAIN_BROKEN: {
+    message: "The per-entry hash chain is broken.",
+    hint: "An entry was inserted, removed, or edited after signing. The break index is shown in the issues list.",
+    docsUrl: VERIFY_URL
+  },
+  STEP_CHAIN_BROKEN: {
+    message: "The per-step hash chain inside one or more entries is broken.",
+    hint: "A decision or tool step was tampered with. The affected entry index is in the issues list.",
+    docsUrl: VERIFY_URL
+  },
+  MANIFEST_INVALID: {
+    message: "manifest.json is missing required fields or uses an unsupported format.",
+    hint: "Re-export the bundle from the CLI \u2014 do not edit manifest.json by hand.",
+    docsUrl: SPEC_URL
+  },
+  FILE_NOT_FOUND: {
+    message: "Receipt not found at the given path.",
+    hint: "Check the path \u2014 a common cause is running from a different working directory than expected.",
+    docsUrl: QUICKSTART_URL
+  },
+  FILE_UNREADABLE: {
+    message: "Receipt exists but could not be read.",
+    hint: "Check filesystem permissions on the file.",
+    docsUrl: QUICKSTART_URL
+  },
+  UNKNOWN: {
+    message: "Something went wrong while verifying that bundle.",
+    hint: "Try again with a fresh export. If the error persists, run `aarmos verify` locally to see the raw error.",
+    docsUrl: QUICKSTART_URL
+  }
+};
+function aarmosError(code, overrides = {}) {
+  const base = AARMOS_ERROR_TEMPLATES[code];
+  return {
+    code,
+    message: overrides.message ?? base.message,
+    hint: overrides.hint ?? base.hint,
+    docsUrl: overrides.docsUrl ?? base.docsUrl
+  };
+}
+function formatAarmosErrorLine(err) {
+  return `\u2717 ${err.code}: ${err.message}
+  Next: ${err.hint}
+  Docs: ${err.docsUrl}`;
+}
+function classifyReport(report) {
+  if (report.verdict !== "invalid") return null;
+  if (!report.entriesSha256Ok) return aarmosError("ENTRIES_SHA256_MISMATCH");
+  if (!report.signaturesOk) return aarmosError("SIGNATURE_MISMATCH");
+  if (!report.fingerprintsOk) return aarmosError("FINGERPRINT_MISMATCH");
+  if (!report.chainOk) return aarmosError("CHAIN_BROKEN");
+  if (!report.perStepChainOk) return aarmosError("STEP_CHAIN_BROKEN");
+  if (!report.formatOk) {
+    const specIssue = report.issues.find((i) => i.kind === "spec-version-mismatch");
+    if (specIssue) {
+      return aarmosError("SPEC_VERSION_MISMATCH", {
+        message: specIssue.detail ? `Spec mismatch \u2014 ${specIssue.detail}` : void 0
+      });
+    }
+    return aarmosError("MANIFEST_INVALID");
+  }
+  return aarmosError("UNKNOWN");
+}
+var AarmosErrorException = class extends Error {
+  aarmos;
+  constructor(err) {
+    super(`${err.code}: ${err.message}`);
+    this.name = "AarmosErrorException";
+    this.aarmos = err;
+  }
+};
+
+// 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 {
+  AARMOS_ERROR_TEMPLATES,
+  AarmosErrorException,
   GENESIS_PREV_HASH,
   GENESIS_PREV_STEP_HASH,
+  aarmosError,
   canonicalize,
+  classifyReport,
   computeDeviceFingerprint,
   computeEntryHash,
   computeStepHash,
+  diffCanonical,
+  diffPolicies,
+  diffReceipts,
+  diffToolManifests,
+  formatAarmosErrorLine,
   sha256Hex,
   signedBodyOf,
   utf8,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aarmos/avar-core",
-  "version": "1.0.0",
+  "version": "1.2.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",