@aarmos/avar-core 1.0.0-rc.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aarmatix LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,34 @@
+# @aarmos/avar-core
+
+Reference implementation of the [AVAR specification](../../docs/avar/SPEC.md) — canonical JSON, Ed25519 signature verification, hash-chain math, and bundle verification.
+
+**Pure.** No DOM references, no Node built-ins, no external dependencies. Runs identically in browsers (WebCrypto) and Node.js 20+ (`globalThis.crypto.subtle`).
+
+**Normative.** Consumed by:
+- The Aarmos PWA at `/trust/verify` (browser drop-zone).
+- The `aarmos verify` CLI in [`packages/cli`](../cli/).
+- The internal recorder in `src/lib/avar/` (chain + signature production).
+
+All three call the same `verifyBundle()`. Divergence between them is guarded by the golden fixtures in [`test/fixtures/`](./test/fixtures/) — see spec §9.
+
+## API
+
+```ts
+import {
+  // Types
+  type AvarEntry, type AvarBundle, type VerificationReport,
+  // Canonical JSON
+  canonicalize,
+  // Hash / chain
+  sha256Hex, computeEntryHash, computeStepHash,
+  GENESIS_PREV_HASH, GENESIS_PREV_STEP_HASH,
+  // Signature
+  verifySignature, computeDeviceFingerprint,
+  // Verification (top-level)
+  verifyBundle,
+} from "@avar/core";
+```
+
+## Spec revision
+
+Tracks `avar/1` spec revision `1.0-rc1`. See [`../../docs/avar/CHANGELOG.md`](../../docs/avar/CHANGELOG.md).

package/dist/index.d.ts

@@ -0,0 +1,197 @@
+type TraceStep = ToolStep | TextStep | DecisionStep;
+type ToolStep = {
+    kind: "tool";
+    ts: number;
+    tool: string;
+    argsRedacted: unknown;
+    outputPreview?: string;
+    ok: boolean;
+    ms?: number;
+    error?: string;
+    policyHits?: PolicyHit[];
+    prevStepHash?: string;
+    stepHash?: string;
+};
+type TextStep = {
+    kind: "text";
+    ts: number;
+    preview: string;
+    prevStepHash?: string;
+    stepHash?: string;
+};
+type DecisionStep = {
+    kind: "decision";
+    ts: number;
+    tool: string;
+    /**
+     * Decision label. `ALLOW | MODIFY | DENY | STEP_UP | DEFER` are the
+     * classic policy decisions. Minor spec revisions add sources:
+     *  - `KILL` (Wave 1.2, kill-switch)
+     *  - `ROTATE | REVOKE` (Wave 1.3, vault)
+     *  - `FIRST_CONTACT` (Wave 1.4, egress)
+     *  - future additive values.
+     * Verifiers MUST treat unknown decision strings as opaque data.
+     */
+    decision: string;
+    source: string;
+    reason?: string;
+    note?: string;
+    gates?: {
+        kind: string;
+        source: string;
+    }[];
+    policyFingerprint?: string;
+    policyIssuer?: string;
+    bundleState?: "unknown" | "none" | "valid" | "grace" | "invalid";
+    killSwitchAt?: boolean;
+    /**
+     * Kill-switch scope at the time of the decision (Wave 1.2, `avar/1.1`).
+     * Present on `decision: "KILL"` entries produced by the kill-switch;
+     * MAY appear on other decisions as advisory context. Verifiers treat
+     * unknown values as opaque data.
+     */
+    killScope?: "all" | "writes" | "destructive";
+    /** Optional per-step framework tags — see spec §8. */
+    frameworks?: string[];
+    prevStepHash?: string;
+    stepHash?: string;
+};
+type PolicyHit = {
+    ruleId: string;
+    action: "block" | "downgrade" | "warn" | "allow";
+    reason?: string;
+};
+type AvarEntry = {
+    id: string;
+    ts: number;
+    finishedAt?: number;
+    workspaceId: string;
+    agentId?: string;
+    agentName?: string;
+    agentEmoji?: string;
+    agentColor?: string;
+    queryRedacted: string;
+    steps: TraceStep[];
+    outcome: "ok" | "error" | "aborted";
+    provider?: string;
+    model?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    costUsd?: number;
+    seed?: number | string;
+    systemFingerprint?: string;
+    signature?: string;
+    devicePubKey?: string;
+    deviceFingerprint?: string;
+    policyFingerprint?: string;
+    policyIssuer?: string;
+    parentTraceId?: string | null;
+    delegationChain?: {
+        agentId: string;
+        traceId?: string | null;
+        at: number;
+    }[];
+    prevHash?: string;
+    entryHash?: string;
+    /**
+     * Reserved for multi-seat aggregation (Wave 4). Absent in `avar/1.0`.
+     * When present, verifiers treat it as opaque data and include it in
+     * canonical JSON per §2.
+     */
+    seatId?: string;
+    /** Optional framework tags — see spec §8. */
+    frameworks?: string[];
+} & {
+    [k: `x-${string}`]: unknown;
+};
+type BundleManifest = {
+    format: "avar/1";
+    generatedAt: string;
+    producer: {
+        name: string;
+        version: string;
+    };
+    entryCount: number;
+    entriesSha256: string;
+    chainHead: {
+        entryHash: string;
+        index: number;
+    };
+    devicePublicKeys: string[];
+};
+type BundlePubKeys = {
+    keys: Array<{
+        kid: string;
+        algorithm: "Ed25519";
+        publicKey: string;
+    }>;
+};
+type AvarBundle = {
+    /** Contents of `SPEC-VERSION` file — MUST equal `"avar/1"`. */
+    specVersion: string;
+    manifest: BundleManifest;
+    /** Raw bytes of `entries.ndjson` — used to verify `entriesSha256`. */
+    entriesNdjsonBytes: Uint8Array;
+    entries: AvarEntry[];
+    pubkeys: BundlePubKeys;
+};
+type VerificationIssue = {
+    index: number;
+    kind: "spec-version-mismatch" | "manifest-invalid" | "entries-parse-failed" | "entries-sha256-mismatch" | "fingerprint-mismatch" | "signature-invalid" | "signature-unsupported" | "chain-broken" | "partial-step-chain" | "step-chain-broken";
+    detail?: string;
+};
+type VerificationReport = {
+    formatOk: boolean;
+    entriesSha256Ok: boolean;
+    chainOk: boolean;
+    perStepChainOk: boolean;
+    signaturesOk: boolean;
+    fingerprintsOk: boolean;
+    entryCount: number;
+    signedCount: number;
+    unsignedCount: number;
+    unchainedCount: number;
+    chainHead: {
+        entryHash: string;
+        index: number;
+    };
+    issues: VerificationIssue[];
+    verdict: "valid" | "invalid" | "valid-with-warnings";
+};
+
+declare function canonicalize(value: unknown): string;
+/** UTF-8 encode a canonical string for hashing. */
+declare function utf8(s: string): Uint8Array;
+
+declare const GENESIS_PREV_HASH = "0000000000000000000000000000000000000000000000000000000000000000";
+declare const GENESIS_PREV_STEP_HASH = "step-genesis:0000000000000000000000000000000000000000000000000000000000000000";
+declare function sha256Hex(input: string | Uint8Array): Promise<string>;
+/**
+ * Compute entry hash per spec §4.1.
+ *
+ * chainBody = canonicalize(entry with { entryHash: undefined,
+ *                                       signature: undefined,
+ *                                       devicePubKey: undefined })
+ *
+ * NOTE: signature and devicePubKey are ALSO excluded because they are not
+ * part of the signed body (spec §3.2). Including them would make the chain
+ * hash change when the signature is added, creating an ordering paradox.
+ */
+declare function computeEntryHash(entry: AvarEntry, prevHash: string): Promise<string>;
+/** Compute per-step hash per spec §4.3. */
+declare function computeStepHash(step: TraceStep, prevStepHash: string): Promise<string>;
+
+/**
+ * Verify an Ed25519 signature over canonical JSON of `signedBody`.
+ * Never throws — returns false on any parse/import/verify failure so
+ * verifier callers can classify the outcome per spec §6.
+ */
+declare function verifySignature(signedBody: unknown, signatureB64u: string, publicKeyB64u: string): Promise<boolean>;
+/** Compute the 12-hex device fingerprint per spec §3.2. */
+declare function computeDeviceFingerprint(publicKeyB64u: string): Promise<string>;
+/** Extract the signed-body view of an AvarEntry per spec §3.2. */
+declare function signedBodyOf(entry: AvarEntry): Omit<AvarEntry, "signature" | "devicePubKey">;
+
+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 };

package/dist/index.js

@@ -0,0 +1,309 @@
+// src/canonicalize.ts
+var NFC = (s) => s.normalize("NFC");
+function encodeString(s) {
+  return JSON.stringify(NFC(s));
+}
+function encodeNumber(n) {
+  if (!Number.isFinite(n)) {
+    throw new Error(`avar-core/canonicalize: non-finite number (${n}) is forbidden.`);
+  }
+  return JSON.stringify(n);
+}
+function canonicalize(value) {
+  if (value === null) return "null";
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "number") return encodeNumber(value);
+  if (typeof value === "string") return encodeString(value);
+  if (typeof value === "undefined") {
+    throw new Error("avar-core/canonicalize: undefined is forbidden at value position.");
+  }
+  if (typeof value === "function" || typeof value === "symbol" || typeof value === "bigint") {
+    throw new Error(`avar-core/canonicalize: ${typeof value} is forbidden.`);
+  }
+  if (Array.isArray(value)) {
+    return "[" + value.map((v) => canonicalize(v)).join(",") + "]";
+  }
+  if (typeof value === "object") {
+    const obj = value;
+    const keys = [];
+    for (const k of Object.keys(obj)) {
+      if (obj[k] === void 0) continue;
+      keys.push(NFC(k));
+    }
+    keys.sort();
+    const parts = new Array(keys.length);
+    for (let i = 0; i < keys.length; i++) {
+      const k = keys[i];
+      const rawVal = obj[k] ?? findKey(obj, k);
+      parts[i] = encodeString(k) + ":" + canonicalize(rawVal);
+    }
+    return "{" + parts.join(",") + "}";
+  }
+  throw new Error(`avar-core/canonicalize: unsupported type ${typeof value}.`);
+}
+function findKey(obj, nfcKey) {
+  for (const k of Object.keys(obj)) {
+    if (NFC(k) === nfcKey) return obj[k];
+  }
+  return void 0;
+}
+function utf8(s) {
+  return new TextEncoder().encode(s);
+}
+
+// src/hash.ts
+var GENESIS_PREV_HASH = "0000000000000000000000000000000000000000000000000000000000000000";
+var GENESIS_PREV_STEP_HASH = "step-genesis:0000000000000000000000000000000000000000000000000000000000000000";
+function getSubtle() {
+  const c = typeof globalThis !== "undefined" ? globalThis.crypto : void 0;
+  if (!c || !c.subtle) {
+    throw new Error(
+      "avar-core: WebCrypto SubtleCrypto is unavailable. Requires Node 20+ or a modern browser."
+    );
+  }
+  return c.subtle;
+}
+async function sha256Hex(input) {
+  const bytes = typeof input === "string" ? utf8(input) : input;
+  const digest = await getSubtle().digest("SHA-256", bytes);
+  return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+async function computeEntryHash(entry, prevHash) {
+  const withPrev = { ...entry, prevHash };
+  const {
+    entryHash: _e,
+    signature: _sig,
+    devicePubKey: _pk,
+    ...rest
+  } = withPrev;
+  void _e;
+  void _sig;
+  void _pk;
+  return sha256Hex(prevHash + "\n" + canonicalize(rest));
+}
+async function computeStepHash(step, prevStepHash) {
+  const asRec = step;
+  const { stepHash: _s, prevStepHash: _p, ...rest } = asRec;
+  void _s;
+  void _p;
+  const withPrev = { ...rest, prevStepHash };
+  return sha256Hex(prevStepHash + "\n" + canonicalize(withPrev));
+}
+
+// src/signature.ts
+function getSubtle2() {
+  const c = typeof globalThis !== "undefined" ? globalThis.crypto : void 0;
+  if (!c || !c.subtle) {
+    throw new Error("avar-core: WebCrypto SubtleCrypto is unavailable.");
+  }
+  return c.subtle;
+}
+function b64uDecode(s) {
+  const b64 = s.replace(/-/g, "+").replace(/_/g, "/") + "===".slice((s.length + 3) % 4);
+  const bin = typeof atob === "function" ? atob(b64) : globalThis.Buffer.from(b64, "base64").toString("binary");
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+async function verifySignature(signedBody, signatureB64u, publicKeyB64u) {
+  try {
+    const raw = b64uDecode(publicKeyB64u);
+    const key = await getSubtle2().importKey("raw", raw, "Ed25519", false, [
+      "verify"
+    ]);
+    const sig = b64uDecode(signatureB64u);
+    const bytes = utf8(canonicalize(signedBody));
+    return await getSubtle2().verify(
+      "Ed25519",
+      key,
+      sig,
+      bytes
+    );
+  } catch {
+    return false;
+  }
+}
+async function computeDeviceFingerprint(publicKeyB64u) {
+  const hex = await sha256Hex(utf8(publicKeyB64u));
+  return hex.slice(0, 12);
+}
+function signedBodyOf(entry) {
+  const { signature: _sig, devicePubKey: _pk, ...rest } = entry;
+  void _sig;
+  void _pk;
+  return rest;
+}
+
+// src/verify.ts
+var SPEC_VERSION = "avar/1";
+async function verifyBundle(bundle) {
+  const issues = [];
+  let formatOk = true;
+  const specV = bundle.specVersion.trim();
+  if (specV !== SPEC_VERSION) {
+    formatOk = false;
+    issues.push({
+      index: -1,
+      kind: "spec-version-mismatch",
+      detail: `Expected "${SPEC_VERSION}", got "${specV}".`
+    });
+  }
+  if (bundle.manifest.format !== SPEC_VERSION) {
+    formatOk = false;
+    issues.push({
+      index: -1,
+      kind: "manifest-invalid",
+      detail: `manifest.format expected "${SPEC_VERSION}", got "${bundle.manifest.format}".`
+    });
+  }
+  const actualSha = await sha256Hex(bundle.entriesNdjsonBytes);
+  const entriesSha256Ok = actualSha === bundle.manifest.entriesSha256;
+  if (!entriesSha256Ok) {
+    issues.push({
+      index: -1,
+      kind: "entries-sha256-mismatch",
+      detail: `Expected ${bundle.manifest.entriesSha256}, got ${actualSha}.`
+    });
+  }
+  const entries = bundle.entries;
+  const entryCount = entries.length;
+  let signaturesOk = true;
+  let fingerprintsOk = true;
+  let signedCount = 0;
+  let unsignedCount = 0;
+  for (let i = 0; i < entries.length; i++) {
+    const e = entries[i];
+    const hasSig = typeof e.signature === "string" && typeof e.devicePubKey === "string";
+    if (!hasSig) {
+      unsignedCount++;
+      continue;
+    }
+    signedCount++;
+    if (typeof e.deviceFingerprint === "string") {
+      const expected = await computeDeviceFingerprint(e.devicePubKey);
+      if (expected !== e.deviceFingerprint) {
+        fingerprintsOk = false;
+        issues.push({
+          index: i,
+          kind: "fingerprint-mismatch",
+          detail: `Expected ${expected}, got ${e.deviceFingerprint}.`
+        });
+      }
+    }
+    const ok = await verifySignature(signedBodyOf(e), e.signature, e.devicePubKey);
+    if (!ok) {
+      signaturesOk = false;
+      issues.push({ index: i, kind: "signature-invalid" });
+    }
+  }
+  let chainOk = true;
+  let unchainedCount = 0;
+  let expectedPrev = GENESIS_PREV_HASH;
+  for (let i = 0; i < entries.length; i++) {
+    const e = entries[i];
+    const isLegacyUnchained = !e.entryHash || !e.prevHash;
+    if (isLegacyUnchained) {
+      unchainedCount++;
+      expectedPrev = GENESIS_PREV_HASH;
+      continue;
+    }
+    if (e.prevHash !== expectedPrev) {
+      chainOk = false;
+      issues.push({
+        index: i,
+        kind: "chain-broken",
+        detail: `prevHash mismatch at entry ${i}.`
+      });
+    }
+    const recomputed = await computeEntryHash(e, e.prevHash);
+    if (recomputed !== e.entryHash) {
+      chainOk = false;
+      issues.push({
+        index: i,
+        kind: "chain-broken",
+        detail: `entryHash mismatch at entry ${i} (body modified after signing).`
+      });
+    }
+    expectedPrev = e.entryHash;
+  }
+  const perStepChainOk = await verifyAllStepChains(entries, issues);
+  const chainHead = computeChainHead(entries);
+  const anyHardFail = !formatOk || !entriesSha256Ok || !chainOk || !perStepChainOk || !signaturesOk || !fingerprintsOk;
+  const verdict = anyHardFail ? "invalid" : unsignedCount > 0 || unchainedCount > 0 ? "valid-with-warnings" : "valid";
+  return {
+    formatOk,
+    entriesSha256Ok,
+    chainOk,
+    perStepChainOk,
+    signaturesOk,
+    fingerprintsOk,
+    entryCount,
+    signedCount,
+    unsignedCount,
+    unchainedCount,
+    chainHead,
+    issues,
+    verdict
+  };
+}
+async function verifyAllStepChains(entries, issues) {
+  let ok = true;
+  for (let i = 0; i < entries.length; i++) {
+    const e = entries[i];
+    if (!Array.isArray(e.steps) || e.steps.length === 0) continue;
+    const anyChained = e.steps.some(hasChainFields);
+    const allChained = e.steps.every(hasChainFields);
+    if (anyChained && !allChained) {
+      ok = false;
+      issues.push({ index: i, kind: "partial-step-chain" });
+      continue;
+    }
+    if (!anyChained) continue;
+    let prev = "step-genesis:0000000000000000000000000000000000000000000000000000000000000000";
+    for (let j = 0; j < e.steps.length; j++) {
+      const s = e.steps[j];
+      if (s.prevStepHash !== prev) {
+        ok = false;
+        issues.push({
+          index: i,
+          kind: "step-chain-broken",
+          detail: `entry ${i} step ${j}: prevStepHash mismatch.`
+        });
+      }
+      const recomputed = await computeStepHash(s, s.prevStepHash);
+      if (recomputed !== s.stepHash) {
+        ok = false;
+        issues.push({
+          index: i,
+          kind: "step-chain-broken",
+          detail: `entry ${i} step ${j}: stepHash mismatch (step body modified).`
+        });
+      }
+      prev = s.stepHash;
+    }
+  }
+  return ok;
+}
+function hasChainFields(s) {
+  return typeof s.prevStepHash === "string" && typeof s.stepHash === "string";
+}
+function computeChainHead(entries) {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const e = entries[i];
+    if (e.entryHash) return { entryHash: e.entryHash, index: i };
+  }
+  return { entryHash: "", index: -1 };
+}
+export {
+  GENESIS_PREV_HASH,
+  GENESIS_PREV_STEP_HASH,
+  canonicalize,
+  computeDeviceFingerprint,
+  computeEntryHash,
+  computeStepHash,
+  sha256Hex,
+  signedBodyOf,
+  utf8,
+  verifyBundle,
+  verifySignature
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@aarmos/avar-core",
+  "version": "1.0.0-rc.1",
+  "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",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "aarmos",
+    "avar",
+    "audit",
+    "hash-chain",
+    "ed25519",
+    "verifier"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aarmatix/aarmos.git",
+    "directory": "packages/avar-core"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.2"
+  }
+}