@aarmos/avar-core 1.1.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,80 +194,43 @@ declare function signedBodyOf(entry: AvarEntry): Omit<AvarEntry, "signature" | "
 
 declare function verifyBundle(bundle: AvarBundle): Promise<VerificationReport>;
 
-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[];
-};
+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;
 /**
- * Compare two AVAR receipts. Accepts full bundles OR single entries.
- * Entries are matched by `id`, not by index — reordering is not a diff.
+ * 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 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;
+declare class AarmosErrorException extends Error {
+    readonly aarmos: AarmosError;
+    constructor(err: AarmosError);
+}
 
-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 };
+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

@@ -295,6 +295,138 @@ 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);
@@ -454,9 +586,13 @@ 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,
@@ -464,6 +600,7 @@ export {
   diffPolicies,
   diffReceipts,
   diffToolManifests,
+  formatAarmosErrorLine,
   sha256Hex,
   signedBodyOf,
   utf8,

package/package.json

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