jorgex-stack 1.5.0 → 1.6.0

package/dist/quality-verifier.d.ts

@@ -0,0 +1,150 @@
+declare const QUALITY_PROFILES: readonly ["routine", "elevated", "high", "release"];
+type QualityProfile = (typeof QUALITY_PROFILES)[number];
+
+declare const QUALITY_RECEIPT_NAMESPACE: "jorgex.quality.receipt";
+declare const QUALITY_RECEIPT_VERSION: 1;
+type QualityReceiptResultStatus = "pass" | "fail" | "incomplete" | "not-applicable";
+interface QualityReceiptIdentity {
+    profile: QualityProfile;
+    baseSha: string;
+    headSha: string;
+    policyDigest: string;
+}
+interface QualityReceiptProvenance {
+    issuer: string;
+    executionId: string;
+    evidenceLocator: string;
+    evidenceDigest: string;
+}
+interface QualityReceiptPassResult {
+    controlId: string;
+    status: "pass";
+    evidence: string;
+    reason?: string;
+}
+interface QualityReceiptNonPassResult {
+    controlId: string;
+    status: Exclude<QualityReceiptResultStatus, "pass">;
+    evidence?: string;
+    reason?: string;
+}
+type QualityReceiptResult = QualityReceiptPassResult | QualityReceiptNonPassResult;
+interface QualityReceiptCommand {
+    commandId: string;
+    executable: string;
+    argv: string[];
+    exitCode: number;
+    durationMs: number;
+    excerpt: string;
+    outputDigest: string;
+}
+interface QualityReceiptBase {
+    namespace: typeof QUALITY_RECEIPT_NAMESPACE;
+    version: typeof QUALITY_RECEIPT_VERSION;
+    identity: QualityReceiptIdentity;
+    commands: QualityReceiptCommand[];
+    results: QualityReceiptResult[];
+}
+interface QualityReceiptLocal extends QualityReceiptBase {
+    authority: "local";
+    provenance?: QualityReceiptProvenance;
+}
+interface QualityReceiptEnforced extends QualityReceiptBase {
+    authority: "enforced";
+    provenance: QualityReceiptProvenance;
+}
+type QualityReceipt = QualityReceiptLocal | QualityReceiptEnforced;
+
+type ProtectedReference = {
+    ref: string;
+    sha: string;
+};
+type ExternalDecision = "pass" | "fail" | "incomplete";
+type ExternalAttestation = {
+    issuer: string;
+    executionId: string;
+    identity: QualityReceipt["identity"];
+    policyDigest: string;
+    protectedRef: ProtectedReference;
+    producer: {
+        processId: string;
+        worktree: string;
+    };
+    decision: ExternalDecision;
+    subjectDigest: string;
+    evidenceDigest: string;
+    expiresAt: string;
+    proof: string;
+};
+type ExternalEvidence = {
+    locator: string;
+    bytes: Uint8Array;
+    attestation: ExternalAttestation;
+};
+type ExternalEvidenceResolution = {
+    status: "available";
+    evidence: ExternalEvidence;
+} | {
+    status: "expired" | "unavailable";
+    retryable: boolean;
+};
+type AttestationVerification = {
+    authenticated: boolean;
+};
+type ExternalQualityVerifierInput = {
+    receipt: QualityReceipt;
+    expected: {
+        identity: QualityReceipt["identity"];
+        policy: Record<string, unknown>;
+        protectedRef: ProtectedReference;
+        evidenceLocator: string;
+        issuer: string;
+        executionId: string;
+        subjectDigest: string;
+        verifier: {
+            processId: string;
+            worktree: string;
+        };
+    };
+};
+type ExternalQualityVerifierDeps = {
+    /**
+     * Resolves evidence under the caller's own network and resource-safety policy.
+     * This verifier does not fetch, cap, or sandbox the returned bytes; the
+     * implementation must enforce size, timeout, redirect, host, DNS, and SSRF limits.
+     */
+    resolveEvidence(locator: string): Promise<ExternalEvidenceResolution>;
+    /**
+     * Must authenticate the proof and issuer and bind that authentication to all
+     * attestation claims. A true flag based only on shape or the issuer string is
+     * not sufficient because this result is the verifier's authentication gate.
+     */
+    authenticateAttestation(attestation: ExternalAttestation): Promise<AttestationVerification>;
+    now(): string;
+};
+/**
+ * Consumers must treat `incomplete` as a non-pass. `rerunRequired` is only a
+ * retry hint for evidence-resolution failure, not a general approval signal.
+ */
+type ExternalQualityVerifierResult = {
+    status: "pass";
+    rerunRequired: false;
+} | {
+    status: "fail";
+    rerunRequired: false;
+} | {
+    status: "incomplete";
+    rerunRequired: boolean;
+};
+declare function subjectDigestFor(receipt: QualityReceipt): string;
+/**
+ * Verifies an externally enforced receipt against caller-supplied expectations.
+ * A `pass` requires authenticated evidence, all receipt, evidence-binding,
+ * protected-reference, identity, policy, digest, and producer-boundary checks,
+ * a valid expiry, and an attestation decision of `pass`.
+ * This module does not track execution IDs or provide replay protection; callers
+ * must enforce any one-time-use requirement outside this function.
+ */
+declare function verifyExternalQualityReceipt(input: ExternalQualityVerifierInput, deps: ExternalQualityVerifierDeps): Promise<ExternalQualityVerifierResult>;
+
+export { type AttestationVerification, type ExternalAttestation, type ExternalDecision, type ExternalEvidence, type ExternalEvidenceResolution, type ExternalQualityVerifierDeps, type ExternalQualityVerifierInput, type ExternalQualityVerifierResult, type ProtectedReference, subjectDigestFor, verifyExternalQualityReceipt };

package/dist/quality-verifier.js

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+import {
+  QUALITY_PROFILES,
+  canonicalJson,
+  evaluateQualityPolicy,
+  samePath,
+  sha256,
+  validateQualityReceipt
+} from "./chunk-IO2FFZOH.js";
+
+// src/lib/quality-verifier.ts
+import { createHash } from "crypto";
+var COMMIT_SHA_PATTERN = /^[0-9a-f]{40}$/i;
+var SHA256_PATTERN = /^[0-9a-f]{64}$/i;
+var STANDARD_OBJECT_PROTOTYPE_KEYS = new Set(Reflect.ownKeys(Object.prototype));
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function hasOwn(value, key) {
+  return Object.prototype.hasOwnProperty.call(value, key);
+}
+function hasSafePrototype(value) {
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === null || prototype === Object.prototype && Reflect.ownKeys(prototype).every((key) => STANDARD_OBJECT_PROTOTYPE_KEYS.has(key));
+}
+function hasOnlyKeys(value, keys) {
+  const allowed = new Set(keys);
+  return Reflect.ownKeys(value).every((key) => allowed.has(key));
+}
+function hasExactKeys(value, keys) {
+  const ownKeys = Reflect.ownKeys(value);
+  if (ownKeys.length !== keys.length) return false;
+  const allowed = new Set(keys);
+  return ownKeys.every((key) => allowed.has(key));
+}
+function hasText(value) {
+  return typeof value === "string" && value.trim() !== "";
+}
+function isSha(value, pattern) {
+  return typeof value === "string" && pattern.test(value);
+}
+function hexEqual(left, right) {
+  return typeof left === "string" && typeof right === "string" && left.toLowerCase() === right.toLowerCase();
+}
+function isQualityProfile(value) {
+  return typeof value === "string" && QUALITY_PROFILES.includes(value);
+}
+function isQualityReceiptIdentity(value) {
+  if (!isRecord(value) || !hasExactKeys(value, ["profile", "baseSha", "headSha", "policyDigest"])) return false;
+  return isQualityProfile(value.profile) && isSha(value.baseSha, COMMIT_SHA_PATTERN) && isSha(value.headSha, COMMIT_SHA_PATTERN) && isSha(value.policyDigest, SHA256_PATTERN);
+}
+function sameQualityReceiptIdentity(left, right) {
+  return left.profile === right.profile && hexEqual(left.baseSha, right.baseSha) && hexEqual(left.headSha, right.headSha) && hexEqual(left.policyDigest, right.policyDigest);
+}
+function sameProtectedReference(left, right) {
+  return left.ref === right.ref && hexEqual(left.sha, right.sha);
+}
+function isProtectedReference(value) {
+  return isRecord(value) && hasExactKeys(value, ["ref", "sha"]) && hasText(value.ref) && isSha(value.sha, COMMIT_SHA_PATTERN);
+}
+function isVerifierBoundary(value) {
+  return isRecord(value) && hasExactKeys(value, ["processId", "worktree"]) && hasText(value.processId) && hasText(value.worktree);
+}
+function sha256Bytes(bytes) {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+function subjectDigestFor(receipt) {
+  return sha256(canonicalJson({
+    namespace: receipt.namespace,
+    version: receipt.version,
+    authority: receipt.authority,
+    identity: receipt.identity,
+    commands: receipt.commands,
+    results: receipt.results
+  }));
+}
+function isQualityPolicy(value) {
+  if (!isRecord(value) || !hasSafePrototype(value) || !hasOnlyKeys(value, ["profile", "controls"]) || !hasOwn(value, "controls") || !Array.isArray(value.controls)) return false;
+  if (!hasOwn(value, "profile") && "profile" in value) return false;
+  if (hasOwn(value, "profile") && !isQualityProfile(value.profile)) return false;
+  const ids = /* @__PURE__ */ new Set();
+  for (const control of value.controls) {
+    if (!isRecord(control) || !hasSafePrototype(control) || !hasOnlyKeys(control, ["id", "requirement", "notApplicable"]) || !hasOwn(control, "id") || !hasOwn(control, "requirement") || !hasOwn(control, "notApplicable") && "notApplicable" in control || !hasText(control.id) || control.requirement !== "required" && control.requirement !== "optional" || ids.has(control.id) || hasOwn(control, "notApplicable") && typeof control.notApplicable !== "boolean") {
+      return false;
+    }
+    ids.add(control.id);
+  }
+  return true;
+}
+function isAttestation(value) {
+  return isRecord(value) && hasExactKeys(value, [
+    "issuer",
+    "executionId",
+    "identity",
+    "policyDigest",
+    "protectedRef",
+    "producer",
+    "decision",
+    "subjectDigest",
+    "evidenceDigest",
+    "expiresAt",
+    "proof"
+  ]) && hasText(value.issuer) && hasText(value.executionId) && isQualityReceiptIdentity(value.identity) && isSha(value.policyDigest, SHA256_PATTERN) && isProtectedReference(value.protectedRef) && isVerifierBoundary(value.producer) && (value.decision === "pass" || value.decision === "fail" || value.decision === "incomplete") && isSha(value.subjectDigest, SHA256_PATTERN) && isSha(value.evidenceDigest, SHA256_PATTERN) && hasText(value.expiresAt) && hasText(value.proof);
+}
+function isExternalEvidence(value) {
+  return isRecord(value) && hasExactKeys(value, ["locator", "bytes", "attestation"]) && hasText(value.locator) && value.bytes instanceof Uint8Array && isAttestation(value.attestation);
+}
+function isAttestationVerification(value) {
+  return isRecord(value) && Object.prototype.hasOwnProperty.call(value, "authenticated") && typeof value.authenticated === "boolean";
+}
+function isAvailableResolution(value) {
+  return isRecord(value) && hasExactKeys(value, ["status", "evidence"]) && value.status === "available" && isExternalEvidence(value.evidence);
+}
+function isRetryableResolution(value) {
+  return isRecord(value) && hasExactKeys(value, ["status", "retryable"]) && (value.status === "expired" || value.status === "unavailable") && typeof value.retryable === "boolean";
+}
+function prepareVerification(input) {
+  try {
+    const receipt = input.receipt;
+    const expected = input.expected;
+    if (!isRecord(expected) || !isQualityReceiptIdentity(expected.identity) || !isQualityPolicy(expected.policy) || !isProtectedReference(expected.protectedRef) || !isVerifierBoundary(expected.verifier) || !hasText(expected.evidenceLocator) || !hasText(expected.issuer) || !hasText(expected.executionId) || !isSha(expected.subjectDigest, SHA256_PATTERN)) {
+      return null;
+    }
+    validateQualityReceipt(receipt);
+    if (!sameQualityReceiptIdentity(receipt.identity, expected.identity)) return null;
+    if (receipt.authority !== "enforced" || receipt.provenance === void 0) return null;
+    if (receipt.provenance.issuer !== expected.issuer || receipt.provenance.executionId !== expected.executionId || receipt.provenance.evidenceLocator !== expected.evidenceLocator) {
+      return null;
+    }
+    if (!hexEqual(expected.protectedRef.sha, receipt.identity.baseSha)) return null;
+    const policyDigest = sha256(canonicalJson(expected.policy));
+    if (!hexEqual(policyDigest, expected.identity.policyDigest) || !hexEqual(policyDigest, receipt.identity.policyDigest)) {
+      return null;
+    }
+    const policyProfile = expected.policy.profile ?? "routine";
+    if (expected.identity.profile !== policyProfile) return null;
+    const policyEvaluation = evaluateQualityPolicy({
+      profile: expected.policy.profile,
+      controls: expected.policy.controls,
+      results: receipt.results
+    });
+    if (policyEvaluation.status !== "pass") {
+      return {
+        receipt,
+        expected,
+        policyDigest,
+        subjectDigest: expected.subjectDigest,
+        policyStatus: policyEvaluation.status
+      };
+    }
+    const subjectDigest = subjectDigestFor(receipt);
+    if (!hexEqual(subjectDigest, expected.subjectDigest)) return null;
+    return {
+      receipt,
+      expected,
+      policyDigest,
+      subjectDigest,
+      policyStatus: policyEvaluation.status
+    };
+  } catch {
+    return null;
+  }
+}
+function verifyEvidenceBinding(evidence, attestation, prepared) {
+  const { receipt, expected } = prepared;
+  const provenance = receipt.provenance;
+  if (provenance === void 0) return false;
+  const evidenceDigest = sha256Bytes(evidence.bytes);
+  return evidence.locator === expected.evidenceLocator && evidence.locator === provenance.evidenceLocator && hexEqual(evidenceDigest, provenance.evidenceDigest) && hexEqual(evidenceDigest, attestation.evidenceDigest) && hexEqual(attestation.subjectDigest, prepared.subjectDigest) && sameQualityReceiptIdentity(attestation.identity, receipt.identity) && sameQualityReceiptIdentity(attestation.identity, expected.identity) && hexEqual(attestation.policyDigest, prepared.policyDigest) && hexEqual(attestation.policyDigest, receipt.identity.policyDigest) && sameProtectedReference(attestation.protectedRef, expected.protectedRef) && hexEqual(attestation.protectedRef.sha, receipt.identity.baseSha) && attestation.issuer === expected.issuer && attestation.issuer === provenance.issuer && attestation.executionId === expected.executionId && attestation.executionId === provenance.executionId && attestation.producer.processId !== expected.verifier.processId && !samePath(attestation.producer.worktree, expected.verifier.worktree);
+}
+async function verifyAttestation(evidence, prepared, deps) {
+  try {
+    const attestation = snapshotAttestation(evidence.attestation);
+    let verification;
+    try {
+      verification = await deps.authenticateAttestation(attestation);
+    } catch {
+      return null;
+    }
+    if (!isAttestationVerification(verification) || !verification.authenticated) return null;
+    if (!verifyEvidenceBinding(evidence, attestation, prepared)) return null;
+    const nowMs = Date.parse(deps.now());
+    const expiresAtMs = Date.parse(attestation.expiresAt);
+    if (!Number.isFinite(nowMs) || !Number.isFinite(expiresAtMs) || expiresAtMs <= nowMs) return null;
+    return attestation.decision;
+  } catch {
+    return null;
+  }
+}
+function snapshotAttestation(attestation) {
+  const identity = Object.freeze({ ...attestation.identity });
+  const protectedRef = Object.freeze({ ...attestation.protectedRef });
+  const producer = Object.freeze({ ...attestation.producer });
+  return Object.freeze({
+    issuer: attestation.issuer,
+    executionId: attestation.executionId,
+    identity,
+    policyDigest: attestation.policyDigest,
+    protectedRef,
+    producer,
+    decision: attestation.decision,
+    subjectDigest: attestation.subjectDigest,
+    evidenceDigest: attestation.evidenceDigest,
+    expiresAt: attestation.expiresAt,
+    proof: attestation.proof
+  });
+}
+function failureResult() {
+  return { status: "fail", rerunRequired: false };
+}
+async function verifyExternalQualityReceipt(input, deps) {
+  try {
+    const prepared = prepareVerification(input);
+    if (prepared === null) return failureResult();
+    if (prepared.policyStatus === "fail") return failureResult();
+    if (prepared.policyStatus === "incomplete") {
+      return { status: "incomplete", rerunRequired: false };
+    }
+    if (typeof deps?.resolveEvidence !== "function" || typeof deps.authenticateAttestation !== "function" || typeof deps.now !== "function") {
+      return failureResult();
+    }
+    let resolution;
+    try {
+      resolution = await deps.resolveEvidence(prepared.expected.evidenceLocator);
+    } catch {
+      return { status: "incomplete", rerunRequired: true };
+    }
+    if (isRetryableResolution(resolution)) {
+      return { status: "incomplete", rerunRequired: resolution.retryable };
+    }
+    if (!isAvailableResolution(resolution)) return failureResult();
+    const { evidence } = resolution;
+    const decision = await verifyAttestation(evidence, prepared, deps);
+    if (decision === null) return failureResult();
+    if (decision === "incomplete") {
+      return { status: "incomplete", rerunRequired: false };
+    }
+    return {
+      status: decision,
+      rerunRequired: false
+    };
+  } catch {
+    return failureResult();
+  }
+}
+export {
+  subjectDigestFor,
+  verifyExternalQualityReceipt
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jorgex-stack",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Harness multi-agente portable: instala la config JorgeX (agentes, skills, hooks, Engram, MCPs) en Claude Code, Codex CLI, OpenCode y Pi",
   "type": "module",
   "license": "MIT",
@@ -27,6 +27,12 @@
     "upstreams.json",
     "PRD.md"
   ],
+  "exports": {
+    "./quality-verifier": {
+      "types": "./dist/quality-verifier.d.ts",
+      "import": "./dist/quality-verifier.js"
+    }
+  },
   "engines": {
     "node": ">=22.5"
   },