@primust/verifier 1.0.0 → 1.1.0

package/dist/chunk-LTWQK3HT.js

@@ -0,0 +1,432 @@
+// src/v29-envelope.ts
+import { createHash, createPublicKey, verify as cryptoVerify } from "crypto";
+var ENVELOPE_VERSION = "v0.1";
+var ALLOWED_KINDS = /* @__PURE__ */ new Set([
+  "governance_check",
+  "outbound_action",
+  "token_authority_snapshot",
+  "workspace_observation",
+  "contention_event",
+  "scope_claim_lifecycle",
+  "scope_claim_emitted",
+  "turn_context",
+  "tool_execution"
+]);
+var ALLOWED_TRUST_EDGES = /* @__PURE__ */ new Set(["A2T", "A2M", "A2H", "A2A", "A2S", "A2D"]);
+var PROOF_TIER_HIERARCHY = [
+  "attestation",
+  "witnessed",
+  "execution",
+  "operator_bound",
+  "verifiable_inference",
+  "mathematical"
+];
+var TIER_INDEX = Object.fromEntries(
+  PROOF_TIER_HIERARCHY.map((t, i) => [t, i])
+);
+var v29Pass = () => ({ ok: true, reasonCode: null });
+var v29Fail = (code, detail = "") => ({
+  ok: false,
+  reasonCode: code,
+  detail
+});
+function sortValue(v) {
+  if (v === null || typeof v !== "object") return v;
+  if (Array.isArray(v)) return v.map(sortValue);
+  const out = {};
+  for (const k of Object.keys(v).sort()) {
+    out[k] = sortValue(v[k]);
+  }
+  return out;
+}
+function canonicalJson(value) {
+  return JSON.stringify(sortValue(value));
+}
+function canonicalHash(value) {
+  return "sha256:" + createHash("sha256").update(canonicalJson(value)).digest("hex");
+}
+function validateEnvelopeShape(envelope) {
+  if (typeof envelope !== "object" || envelope === null) {
+    return v29Fail("envelope_not_object");
+  }
+  const e = envelope;
+  if (e.envelope_version !== ENVELOPE_VERSION) {
+    return v29Fail(
+      "envelope_version_mismatch",
+      `expected ${ENVELOPE_VERSION}, got ${JSON.stringify(e.envelope_version)}`
+    );
+  }
+  for (const k of ["run_header", "records", "aggregations"]) {
+    if (!(k in e)) return v29Fail("envelope_missing_key", k);
+  }
+  const header = e.run_header;
+  if (typeof header !== "object" || header === null) {
+    return v29Fail("run_header_not_object");
+  }
+  for (const k of ["run_id", "org_id", "opened_at", "target_environment"]) {
+    if (!(k in header)) return v29Fail("run_header_missing_key", k);
+  }
+  const records = e.records;
+  if (!Array.isArray(records)) return v29Fail("records_not_array");
+  for (let i = 0; i < records.length; i++) {
+    const r = records[i];
+    if (typeof r !== "object" || r === null) {
+      return v29Fail("record_not_object", `records[${i}]`);
+    }
+    if (!ALLOWED_KINDS.has(String(r.kind))) {
+      return v29Fail("record_kind_unknown", `records[${i}].kind=${JSON.stringify(r.kind)}`);
+    }
+    if (r.trust_edge != null && !ALLOWED_TRUST_EDGES.has(String(r.trust_edge))) {
+      return v29Fail(
+        "record_trust_edge_unknown",
+        `records[${i}].trust_edge=${JSON.stringify(r.trust_edge)}`
+      );
+    }
+  }
+  return v29Pass();
+}
+function reproduceAggregations(records) {
+  const proofMix = {};
+  for (const t of PROOF_TIER_HIERARCHY) proofMix[t] = 0;
+  const trustEdges = {};
+  let floorIdx = null;
+  let proven = 0;
+  let totalWithTier = 0;
+  for (const r of records) {
+    const tier = r.tier_computed;
+    if (typeof tier === "string" && tier in proofMix) {
+      proofMix[tier] += 1;
+      totalWithTier += 1;
+      const idx = TIER_INDEX[tier];
+      if (floorIdx === null || idx < floorIdx) floorIdx = idx;
+      if (idx > 0) proven += 1;
+    }
+    const edge = r.trust_edge;
+    if (typeof edge === "string" && ALLOWED_TRUST_EDGES.has(edge)) {
+      const slot = trustEdges[edge] ?? { count: 0, tier_floor: null };
+      slot.count += 1;
+      if (typeof tier === "string" && tier in TIER_INDEX) {
+        if (slot.tier_floor === null || TIER_INDEX[tier] < TIER_INDEX[slot.tier_floor]) {
+          slot.tier_floor = tier;
+        }
+      }
+      trustEdges[edge] = slot;
+    }
+  }
+  const provableSurface = totalWithTier > 0 ? Math.round(proven / totalWithTier * 1e4) / 1e4 : 0;
+  return {
+    trust_edges_observed: trustEdges,
+    proof_mix: proofMix,
+    proof_level_floor: floorIdx === null ? null : PROOF_TIER_HIERARCHY[floorIdx],
+    provable_surface: provableSurface,
+    provable_surface_breakdown: {
+      records_with_tier: totalWithTier,
+      records_proven_above_attestation: proven
+    }
+  };
+}
+function validateAggregations(envelope) {
+  const stated = envelope.aggregations ?? {};
+  const expected = reproduceAggregations(
+    envelope.records ?? []
+  );
+  if (canonicalJson(stated) !== canonicalJson(expected)) {
+    return v29Fail(
+      "aggregation_reproduction_mismatch",
+      "stated aggregations differ from per-record reproduction"
+    );
+  }
+  return v29Pass();
+}
+function decodeJsonb(v) {
+  if (v == null) return null;
+  if (typeof v === "string") {
+    try {
+      return JSON.parse(v);
+    } catch {
+      return null;
+    }
+  }
+  return v;
+}
+function reproduceTierCeiling(harnessManifest, surface, tierClaimed) {
+  const ceilings = decodeJsonb(harnessManifest.surface_tier_ceilings) ?? {};
+  const ceiling = ceilings[surface];
+  if (ceiling == null) {
+    return { effective_tier: tierClaimed, tier_ceiling_applied: null };
+  }
+  const claimIdx = TIER_INDEX[tierClaimed] ?? -1;
+  const ceilIdx = TIER_INDEX[ceiling] ?? -1;
+  if (claimIdx <= ceilIdx || claimIdx === -1) {
+    return { effective_tier: tierClaimed, tier_ceiling_applied: null };
+  }
+  return { effective_tier: ceiling, tier_ceiling_applied: ceiling };
+}
+function validateRecordsAgainstHarness(records, harnessManifest) {
+  if (!harnessManifest) return v29Pass();
+  for (let i = 0; i < records.length; i++) {
+    const r = records[i];
+    const tierClaimed = r.tier_claimed;
+    const surface = r.surface;
+    let stored = r.tier_ceiling_applied;
+    if (typeof stored === "string" && stored.length === 0) stored = null;
+    if (typeof tierClaimed !== "string" || typeof surface !== "string") continue;
+    const reproduced = reproduceTierCeiling(harnessManifest, surface, tierClaimed);
+    if (reproduced.tier_ceiling_applied !== (stored ?? null)) {
+      return v29Fail(
+        "harness_tier_ceiling_reproduction_mismatch",
+        `records[${i}] surface=${surface} tier_claimed=${tierClaimed}`
+      );
+    }
+  }
+  return v29Pass();
+}
+function validateRuntimeBindingHash(binding) {
+  const stored = binding.binding_body_canonical_hash;
+  let body = binding.binding_body_canonical_json;
+  if (!body || typeof stored !== "string") {
+    return v29Fail("runtime_binding_missing_body_or_hash");
+  }
+  if (typeof body === "string") {
+    try {
+      body = JSON.parse(body);
+    } catch {
+      return v29Fail("runtime_binding_body_not_json");
+    }
+  }
+  const reproduced = canonicalHash(body);
+  if (reproduced !== stored) {
+    return v29Fail(
+      "runtime_binding_hash_reproduction_mismatch",
+      `stored=${stored.slice(0, 24)}\u2026 reproduced=${reproduced.slice(0, 24)}\u2026`
+    );
+  }
+  return v29Pass();
+}
+function reproduceManifestCanonicalHash(manifest, manifestKind) {
+  let body;
+  if (manifestKind === "agent") {
+    body = {
+      agent_manifest_id: manifest.agent_manifest_id,
+      manifest_version: manifest.manifest_version,
+      org_id: manifest.org_id,
+      issuer_id: manifest.issuer_id,
+      agent_name: manifest.agent_name,
+      agent_kind: manifest.agent_kind,
+      agent_vendor: manifest.agent_vendor,
+      capability_grants: decodeJsonb(manifest.capability_grants),
+      scope_expressions: decodeJsonb(manifest.scope_expressions),
+      reversibility_overrides: decodeJsonb(manifest.reversibility_overrides) ?? {},
+      model_profile_id: manifest.model_profile_id ?? null,
+      agent_behavior_profile_id: manifest.agent_behavior_profile_id ?? null,
+      applicable_action_profiles: decodeJsonb(manifest.applicable_action_profiles) ?? [],
+      issued_at: manifest.issued_at,
+      expires_at: manifest.expires_at
+    };
+  } else {
+    body = {
+      harness_manifest_id: manifest.harness_manifest_id,
+      manifest_version: manifest.manifest_version,
+      org_id: manifest.org_id,
+      issuer_id: manifest.issuer_id,
+      harness_name: manifest.harness_name,
+      harness_bundle_version: manifest.harness_bundle_version,
+      config_hash: manifest.config_hash,
+      native_config_hashes: decodeJsonb(manifest.native_config_hashes) ?? {},
+      surface_tier_ceilings: decodeJsonb(manifest.surface_tier_ceilings),
+      declared_blind_spots: decodeJsonb(manifest.declared_blind_spots) ?? [],
+      detector_posture: decodeJsonb(manifest.detector_posture) ?? {},
+      active_check_classes: decodeJsonb(manifest.active_check_classes) ?? [],
+      issued_at: manifest.issued_at,
+      expires_at: manifest.expires_at
+    };
+  }
+  return canonicalHash(body);
+}
+function validateManifestCanonicalHash(manifest, manifestKind) {
+  const stated = manifest.canonical_json_hash;
+  if (typeof stated !== "string") return v29Fail("manifest_missing_canonical_hash");
+  const reproduced = reproduceManifestCanonicalHash(manifest, manifestKind);
+  if (reproduced !== stated) {
+    return v29Fail(
+      "manifest_canonical_hash_reproduction_mismatch",
+      `${manifestKind}: stored=${stated.slice(0, 24)}\u2026 reproduced=${reproduced.slice(0, 24)}\u2026`
+    );
+  }
+  return v29Pass();
+}
+function canonicalBodyBytes(body) {
+  return Buffer.from(canonicalJson(body), "utf-8");
+}
+function decodeBase64Tolerant(s) {
+  const normalized = s.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = normalized + "=".repeat((4 - normalized.length % 4) % 4);
+  return Buffer.from(padded, "base64");
+}
+function verifyEd25519(bodyCanonicalBytes, signatureB64, publicKeyBytes) {
+  if (!bodyCanonicalBytes.length || !signatureB64 || publicKeyBytes.length !== 32) {
+    return false;
+  }
+  try {
+    const sigBytes = decodeBase64Tolerant(signatureB64);
+    const der = Buffer.concat([
+      Buffer.from([48, 42, 48, 5, 6, 3, 43, 101, 112, 3, 33, 0]),
+      Buffer.from(publicKeyBytes)
+    ]);
+    const keyObj = createPublicKey({ key: der, format: "der", type: "spki" });
+    return cryptoVerify(null, bodyCanonicalBytes, keyObj, sigBytes);
+  } catch {
+    return false;
+  }
+}
+function manifestCanonicalBody(manifest, kind) {
+  if (kind === "agent") {
+    return {
+      agent_manifest_id: manifest.agent_manifest_id ?? null,
+      manifest_version: manifest.manifest_version ?? null,
+      org_id: manifest.org_id ?? null,
+      issuer_id: manifest.issuer_id ?? null,
+      agent_name: manifest.agent_name ?? null,
+      agent_kind: manifest.agent_kind ?? null,
+      agent_vendor: manifest.agent_vendor ?? null,
+      capability_grants: decodeJsonb(manifest.capability_grants) ?? null,
+      scope_expressions: decodeJsonb(manifest.scope_expressions) ?? null,
+      reversibility_overrides: decodeJsonb(manifest.reversibility_overrides) ?? {},
+      model_profile_id: manifest.model_profile_id ?? null,
+      agent_behavior_profile_id: manifest.agent_behavior_profile_id ?? null,
+      applicable_action_profiles: decodeJsonb(manifest.applicable_action_profiles) ?? [],
+      issued_at: manifest.issued_at ?? null,
+      expires_at: manifest.expires_at ?? null
+    };
+  }
+  return {
+    harness_manifest_id: manifest.harness_manifest_id ?? null,
+    manifest_version: manifest.manifest_version ?? null,
+    org_id: manifest.org_id ?? null,
+    issuer_id: manifest.issuer_id ?? null,
+    harness_name: manifest.harness_name ?? null,
+    harness_bundle_version: manifest.harness_bundle_version ?? null,
+    config_hash: manifest.config_hash ?? null,
+    native_config_hashes: decodeJsonb(manifest.native_config_hashes) ?? {},
+    surface_tier_ceilings: decodeJsonb(manifest.surface_tier_ceilings) ?? {},
+    declared_blind_spots: decodeJsonb(manifest.declared_blind_spots) ?? [],
+    detector_posture: decodeJsonb(manifest.detector_posture) ?? {},
+    active_check_classes: decodeJsonb(manifest.active_check_classes) ?? [],
+    issued_at: manifest.issued_at ?? null,
+    expires_at: manifest.expires_at ?? null
+  };
+}
+function validateRuntimeBindingSignature(binding, pubkeyResolver) {
+  if (!pubkeyResolver) return v29Pass();
+  const sig = binding.signature;
+  const kid = binding.kms_kid;
+  let body = binding.binding_body_canonical_json;
+  if (!body || typeof sig !== "string" || typeof kid !== "string") {
+    return v29Fail(
+      "runtime_binding_signature_missing",
+      `body=${!!body} sig=${!!sig} kid=${!!kid}`
+    );
+  }
+  if (typeof body === "string") {
+    try {
+      body = JSON.parse(body);
+    } catch {
+      return v29Fail("runtime_binding_body_not_json");
+    }
+  }
+  let pubkey;
+  try {
+    pubkey = pubkeyResolver(kid);
+  } catch (e) {
+    return v29Fail("runtime_binding_pubkey_unresolvable", `kid=${kid}: ${e}`);
+  }
+  if (!verifyEd25519(canonicalBodyBytes(body), sig, pubkey)) {
+    return v29Fail("runtime_binding_signature_invalid");
+  }
+  return v29Pass();
+}
+function validateManifestSignature(manifest, manifestKind, pubkeyResolver) {
+  if (!pubkeyResolver) return v29Pass();
+  const sig = manifest.signature;
+  const kid = manifest.kms_kid;
+  if (typeof sig !== "string" || typeof kid !== "string") {
+    return v29Fail(
+      `${manifestKind}_manifest_signature_missing`,
+      `sig=${!!sig} kid=${!!kid}`
+    );
+  }
+  let pubkey;
+  try {
+    pubkey = pubkeyResolver(kid);
+  } catch (e) {
+    return v29Fail(`${manifestKind}_manifest_pubkey_unresolvable`, `kid=${kid}: ${e}`);
+  }
+  const body = manifestCanonicalBody(manifest, manifestKind);
+  if (!verifyEd25519(canonicalBodyBytes(body), sig, pubkey)) {
+    return v29Fail(`${manifestKind}_manifest_signature_invalid`);
+  }
+  return v29Pass();
+}
+function verifyV29(opts) {
+  if (opts.requireSignatures && !opts.pubkeyResolver) {
+    return v29Fail(
+      "signature_resolver_required",
+      "requireSignatures=true but no pubkeyResolver was provided"
+    );
+  }
+  let res = validateEnvelopeShape(opts.envelope);
+  if (!res.ok) return res;
+  res = validateAggregations(opts.envelope);
+  if (!res.ok) return res;
+  const rh = opts.envelope.run_header ?? {};
+  const bound = rh.bound_manifests ?? {};
+  const harnessBlock = opts.harnessManifest ?? bound.harness;
+  const agentBlock = opts.agentManifest ?? bound.agent;
+  const resolver = opts.pubkeyResolver ?? null;
+  res = validateRecordsAgainstHarness(
+    opts.envelope.records ?? [],
+    harnessBlock ?? null
+  );
+  if (!res.ok) return res;
+  if (opts.runtimeBinding) {
+    res = validateRuntimeBindingHash(opts.runtimeBinding);
+    if (!res.ok) return res;
+    res = validateRuntimeBindingSignature(opts.runtimeBinding, resolver);
+    if (!res.ok) return res;
+  }
+  if (agentBlock) {
+    res = validateManifestCanonicalHash(agentBlock, "agent");
+    if (!res.ok) return res;
+    res = validateManifestSignature(agentBlock, "agent", resolver);
+    if (!res.ok) return res;
+  }
+  if (harnessBlock) {
+    res = validateManifestCanonicalHash(harnessBlock, "harness");
+    if (!res.ok) return res;
+    res = validateManifestSignature(harnessBlock, "harness", resolver);
+    if (!res.ok) return res;
+  }
+  return v29Pass();
+}
+
+export {
+  ENVELOPE_VERSION,
+  ALLOWED_KINDS,
+  ALLOWED_TRUST_EDGES,
+  PROOF_TIER_HIERARCHY,
+  v29Pass,
+  v29Fail,
+  canonicalJson,
+  canonicalHash,
+  validateEnvelopeShape,
+  reproduceAggregations,
+  validateAggregations,
+  reproduceTierCeiling,
+  validateRecordsAgainstHarness,
+  validateRuntimeBindingHash,
+  reproduceManifestCanonicalHash,
+  validateManifestCanonicalHash,
+  validateRuntimeBindingSignature,
+  validateManifestSignature,
+  verifyV29
+};