agentic-qe 3.12.2 → 3.13.0

package/dist/learning/qe-flywheel/platform-signer.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Witness-key bridge (qe-harness issue #7) — sign flywheel receipts with the ONE
+ * Cognitum platform identity instead of a self-generated key, so every QE receipt
+ * (engine campaign · flywheel promotion · coherence verdict) chains to the same
+ * externally-verifiable key (`QE_WITNESS_PUBLIC_KEYS_JSON` allowlist, fingerprint
+ * `f1ac28607da49ec1`).
+ *
+ * `createSigner` already accepts a 32-byte Ed25519 seed → deterministic keypair.
+ * The platform key is delivered as `QE_WITNESS_SIGNING_KEY` — a JSON
+ * `{ publicKey, privateKey }` of PEM strings (same shape qe-harness Stage-B reads
+ * from Secret Manager). We derive the seed from that private key and hand it to
+ * `createSigner`, reproducing the exact platform keypair.
+ *
+ * Graceful: returns null when the env var is absent/malformed, so the flywheel
+ * keeps its self-generated-key behaviour where the platform key isn't provided.
+ * Env-reading lives HERE, not in the dependency-free `receipt.ts` core.
+ */
+import { type Signer } from './receipt.js';
+/**
+ * Extract the raw 32-byte Ed25519 seed from a PKCS#8 private-key PEM. Throws if the
+ * key is not an Ed25519 PKCS#8 key (wrong curve / format).
+ */
+export declare function seedFromPkcs8Pem(privateKeyPem: string): Buffer;
+/**
+ * Build a {@link Signer} bound to the Cognitum platform identity from
+ * `QE_WITNESS_SIGNING_KEY`, or null when it is unset/malformed (graceful fallback).
+ * The returned signer's `keyId` equals the platform witness fingerprint, so a
+ * verifier can attribute the receipt to the platform via the same allowlist that
+ * accepts qe-harness evidence bundles.
+ */
+export declare function platformSigner(env?: NodeJS.ProcessEnv): Signer | null;
+//# sourceMappingURL=platform-signer.d.ts.map

package/dist/learning/qe-flywheel/platform-signer.js

@@ -0,0 +1,60 @@
+/**
+ * Witness-key bridge (qe-harness issue #7) — sign flywheel receipts with the ONE
+ * Cognitum platform identity instead of a self-generated key, so every QE receipt
+ * (engine campaign · flywheel promotion · coherence verdict) chains to the same
+ * externally-verifiable key (`QE_WITNESS_PUBLIC_KEYS_JSON` allowlist, fingerprint
+ * `f1ac28607da49ec1`).
+ *
+ * `createSigner` already accepts a 32-byte Ed25519 seed → deterministic keypair.
+ * The platform key is delivered as `QE_WITNESS_SIGNING_KEY` — a JSON
+ * `{ publicKey, privateKey }` of PEM strings (same shape qe-harness Stage-B reads
+ * from Secret Manager). We derive the seed from that private key and hand it to
+ * `createSigner`, reproducing the exact platform keypair.
+ *
+ * Graceful: returns null when the env var is absent/malformed, so the flywheel
+ * keeps its self-generated-key behaviour where the platform key isn't provided.
+ * Env-reading lives HERE, not in the dependency-free `receipt.ts` core.
+ */
+import { createPrivateKey } from 'node:crypto';
+import { createSigner } from './receipt.js';
+/** DER prefix of an Ed25519 PKCS#8 private key (16 bytes) preceding the 32-byte seed. */
+const ED25519_PKCS8_PREFIX = '302e020100300506032b657004220420';
+/**
+ * Extract the raw 32-byte Ed25519 seed from a PKCS#8 private-key PEM. Throws if the
+ * key is not an Ed25519 PKCS#8 key (wrong curve / format).
+ */
+export function seedFromPkcs8Pem(privateKeyPem) {
+    const der = createPrivateKey(privateKeyPem).export({ format: 'der', type: 'pkcs8' });
+    if (der.length !== 48 || der.subarray(0, 16).toString('hex') !== ED25519_PKCS8_PREFIX) {
+        throw new Error('not an Ed25519 PKCS#8 private key (cannot derive a 32-byte seed)');
+    }
+    return Buffer.from(der.subarray(16, 48));
+}
+/**
+ * Build a {@link Signer} bound to the Cognitum platform identity from
+ * `QE_WITNESS_SIGNING_KEY`, or null when it is unset/malformed (graceful fallback).
+ * The returned signer's `keyId` equals the platform witness fingerprint, so a
+ * verifier can attribute the receipt to the platform via the same allowlist that
+ * accepts qe-harness evidence bundles.
+ */
+export function platformSigner(env = process.env) {
+    const raw = env.QE_WITNESS_SIGNING_KEY;
+    if (!raw)
+        return null;
+    let key;
+    try {
+        key = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!key.privateKey)
+        return null;
+    try {
+        return createSigner(seedFromPkcs8Pem(key.privateKey));
+    }
+    catch {
+        return null; // wrong key type / unparseable — fall back to a self-generated signer
+    }
+}
+//# sourceMappingURL=platform-signer.js.map

package/dist/learning/qe-flywheel/receipt.js

@@ -10,9 +10,16 @@
  * Ed25519 via Node's built-in crypto — dependency-free (ADR-118 §6).
  */
 import { generateKeyPairSync, createPrivateKey, createPublicKey, sign as edSign, verify as edVerify, createHash, } from 'node:crypto';
-/** Derive a stable key id from a public key PEM. */
+/**
+ * Derive a stable key id from a public key PEM. The PEM is trimmed first so the id
+ * is invariant to trailing whitespace (PEM exports carry a trailing newline) AND
+ * matches the Cognitum platform witness fingerprint scheme — `sha256(pem.trim())`
+ * truncated to 16 hex (qe-harness `witness.ts` / meta-llm `qe-witness.ts`). This lets
+ * a flywheel receipt signed with the platform key carry the SAME id the platform
+ * allowlist (`QE_WITNESS_PUBLIC_KEYS_JSON`) recognizes. See platform-signer.ts.
+ */
 function keyIdOf(publicKeyPem) {
-    return createHash('sha256').update(publicKeyPem).digest('hex').slice(0, 16);
+    return createHash('sha256').update(publicKeyPem.trim()).digest('hex').slice(0, 16);
 }
 /**
  * Create an Ed25519 signer. With a 32-byte seed (hex or Buffer) the keypair is

package/dist/learning/qe-flywheel/witness-verify.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Cross-side witness verification (ADR-124 M2.2) — the single verifier that
+ * reconciles AQE's flywheel receipts with the Cognitum `qe-harness` witness
+ * bundles so QE evidence signed by the shared platform identity
+ * (fingerprint `f1ac28607da49ec1`) is verifiable on either side.
+ *
+ * WHAT WAS ALREADY ALIGNED (the bridge that exists): both sides use Ed25519,
+ * the same env secret `QE_WITNESS_SIGNING_KEY` (JSON `{publicKey,privateKey}`
+ * PEM), and the SAME key-id/fingerprint scheme `sha256(pem.trim()).slice(0,16)`
+ * — so both can sign AS the platform identity. `keyFingerprint()` here is
+ * byte-identical to `receipt.ts` `keyIdOf` and to qe-harness `witness.ts`.
+ *
+ * WHAT THIS RECONCILES: the two SIGNED ARTIFACTS are not natively
+ * cross-verifiable — AQE signs a fixed-field-order JSON body as HEX; qe-harness
+ * signs a `sha256:`-prefixed digest of a recursively key-sorted `stableStringify`
+ * as BASE64, wrapped in a nested `witness{}`. This module verifies BOTH.
+ *
+ * TWO EXTERNAL DEPENDENCIES (tracked, need the qe-harness owner — see M2.2 notes):
+ *   1. The public key for `f1ac28607da49ec1` is committed to NEITHER repo (it
+ *      lives on meta-llm). Offline verification of platform-signed artifacts
+ *      needs it provisioned via `QE_WITNESS_PUBLIC_KEYS_JSON`. This verifier is
+ *      READY the moment that allowlist is populated.
+ *   2. The qe-harness bundle format here is implemented to the documented
+ *      algorithm; byte-parity must be confirmed against a REAL qe-harness sample
+ *      bundle before it gates anything (see witness-verify.test.ts).
+ *
+ * No new deps — node:crypto only. Reuses receipt.ts for the AQE path.
+ */
+import { type EvolveReceipt } from './receipt.js';
+/** Public-key allowlist: fingerprint (`sha256(pem)[:16]`) → SPKI PEM. */
+export type PublicKeyAllowlist = Map<string, string>;
+/** Byte-identical to receipt.ts `keyIdOf` and qe-harness `witness.ts` fingerprint. */
+export declare function keyFingerprint(publicKeyPem: string): string;
+/**
+ * Load the trusted public-key allowlist from `QE_WITNESS_PUBLIC_KEYS_JSON`
+ * (`{ "<fingerprint>": "<SPKI PEM>", ... }`). Empty map when unset/unparseable —
+ * callers decide whether an empty allowlist means "verify signature only" (AQE
+ * receipts carry their own PEM) or "reject" (platform bundles need a trust root).
+ */
+export declare function loadAllowlist(json?: string | undefined): PublicKeyAllowlist;
+/**
+ * Deterministic serialization matching qe-harness `stableStringify`: recursive
+ * key-sort on objects, array order preserved. This MUST stay byte-identical to
+ * the qe-harness implementation or digests will not match.
+ */
+export declare function stableStringify(value: unknown): string;
+/** qe-harness canonical digest: `sha256:` + sha256(stableStringify(bundle − digest − witness)). */
+export declare function canonicalDigest(bundle: Record<string, unknown>): string;
+/** The qe-harness witness envelope (packages/engine/src/types.ts). */
+export interface HarnessWitness {
+    alg: 'ed25519';
+    digest: string;
+    /** base64 Ed25519 signature over `digest`. */
+    signature: string;
+    publicKeyFingerprint: string;
+    signedAt?: string;
+}
+export type WitnessFormat = 'aqe-receipt' | 'harness-witness' | 'unknown';
+export interface VerifyResult {
+    valid: boolean;
+    format: WitnessFormat;
+    fingerprint?: string;
+    reason?: string;
+}
+/**
+ * Verify an AQE flywheel receipt. When an allowlist is provided and non-empty,
+ * the receipt's embedded public key must be present (by fingerprint) AND match;
+ * an empty allowlist verifies the signature against the receipt's own PEM only.
+ * NOTE: this is signature verification; the full AQE trust model ALSO re-executes
+ * the frozen gate (ADR-120) — do that separately for promotion decisions.
+ */
+export declare function verifyAqeReceipt(receipt: EvolveReceipt, allowlist?: PublicKeyAllowlist, opts?: {
+    allowSelfSigned?: boolean;
+}): VerifyResult;
+/**
+ * Verify a qe-harness witness bundle. Requires the signer's public key in the
+ * allowlist (platform bundles do NOT embed their PEM). Recomputes the canonical
+ * digest to detect payload tampering, then Ed25519-verifies the base64 signature
+ * over the digest string.
+ */
+export declare function verifyHarnessWitness(bundle: Record<string, unknown> & {
+    witness: HarnessWitness;
+}, allowlist: PublicKeyAllowlist): VerifyResult;
+/** Detect the artifact format and dispatch to the right verifier. */
+export declare function verifyWitness(artifact: unknown, allowlist?: PublicKeyAllowlist): VerifyResult;
+//# sourceMappingURL=witness-verify.d.ts.map

package/dist/learning/qe-flywheel/witness-verify.js

@@ -0,0 +1,156 @@
+/**
+ * Cross-side witness verification (ADR-124 M2.2) — the single verifier that
+ * reconciles AQE's flywheel receipts with the Cognitum `qe-harness` witness
+ * bundles so QE evidence signed by the shared platform identity
+ * (fingerprint `f1ac28607da49ec1`) is verifiable on either side.
+ *
+ * WHAT WAS ALREADY ALIGNED (the bridge that exists): both sides use Ed25519,
+ * the same env secret `QE_WITNESS_SIGNING_KEY` (JSON `{publicKey,privateKey}`
+ * PEM), and the SAME key-id/fingerprint scheme `sha256(pem.trim()).slice(0,16)`
+ * — so both can sign AS the platform identity. `keyFingerprint()` here is
+ * byte-identical to `receipt.ts` `keyIdOf` and to qe-harness `witness.ts`.
+ *
+ * WHAT THIS RECONCILES: the two SIGNED ARTIFACTS are not natively
+ * cross-verifiable — AQE signs a fixed-field-order JSON body as HEX; qe-harness
+ * signs a `sha256:`-prefixed digest of a recursively key-sorted `stableStringify`
+ * as BASE64, wrapped in a nested `witness{}`. This module verifies BOTH.
+ *
+ * TWO EXTERNAL DEPENDENCIES (tracked, need the qe-harness owner — see M2.2 notes):
+ *   1. The public key for `f1ac28607da49ec1` is committed to NEITHER repo (it
+ *      lives on meta-llm). Offline verification of platform-signed artifacts
+ *      needs it provisioned via `QE_WITNESS_PUBLIC_KEYS_JSON`. This verifier is
+ *      READY the moment that allowlist is populated.
+ *   2. The qe-harness bundle format here is implemented to the documented
+ *      algorithm; byte-parity must be confirmed against a REAL qe-harness sample
+ *      bundle before it gates anything (see witness-verify.test.ts).
+ *
+ * No new deps — node:crypto only. Reuses receipt.ts for the AQE path.
+ */
+import { createHash, verify as edVerify, createPublicKey } from 'node:crypto';
+import { verifySignature, receiptBodyString } from './receipt.js';
+/** Byte-identical to receipt.ts `keyIdOf` and qe-harness `witness.ts` fingerprint. */
+export function keyFingerprint(publicKeyPem) {
+    return createHash('sha256').update(publicKeyPem.trim()).digest('hex').slice(0, 16);
+}
+/**
+ * Load the trusted public-key allowlist from `QE_WITNESS_PUBLIC_KEYS_JSON`
+ * (`{ "<fingerprint>": "<SPKI PEM>", ... }`). Empty map when unset/unparseable —
+ * callers decide whether an empty allowlist means "verify signature only" (AQE
+ * receipts carry their own PEM) or "reject" (platform bundles need a trust root).
+ */
+export function loadAllowlist(json = process.env.QE_WITNESS_PUBLIC_KEYS_JSON) {
+    const map = new Map();
+    if (!json)
+        return map;
+    try {
+        const obj = JSON.parse(json);
+        for (const [fp, pem] of Object.entries(obj)) {
+            if (typeof pem === 'string')
+                map.set(fp, pem);
+        }
+    }
+    catch {
+        // An unparseable allowlist yields an empty (fail-closed) trust root — but log
+        // it loudly, or a typo'd env var silently disables verification (qe-court finding).
+        console.error('[witness-verify] QE_WITNESS_PUBLIC_KEYS_JSON is set but not valid JSON — ' +
+            'treating the trust root as EMPTY (verification will fail closed).');
+    }
+    return map;
+}
+/**
+ * Deterministic serialization matching qe-harness `stableStringify`: recursive
+ * key-sort on objects, array order preserved. This MUST stay byte-identical to
+ * the qe-harness implementation or digests will not match.
+ */
+export function stableStringify(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return '[' + value.map(stableStringify).join(',') + ']';
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    return '{' + keys.map((k) => JSON.stringify(k) + ':' + stableStringify(obj[k])).join(',') + '}';
+}
+/** qe-harness canonical digest: `sha256:` + sha256(stableStringify(bundle − digest − witness)). */
+export function canonicalDigest(bundle) {
+    const rest = {};
+    for (const [k, v] of Object.entries(bundle)) {
+        if (k === 'digest' || k === 'witness')
+            continue;
+        rest[k] = v;
+    }
+    return 'sha256:' + createHash('sha256').update(stableStringify(rest)).digest('hex');
+}
+/**
+ * Verify an AQE flywheel receipt. When an allowlist is provided and non-empty,
+ * the receipt's embedded public key must be present (by fingerprint) AND match;
+ * an empty allowlist verifies the signature against the receipt's own PEM only.
+ * NOTE: this is signature verification; the full AQE trust model ALSO re-executes
+ * the frozen gate (ADR-120) — do that separately for promotion decisions.
+ */
+export function verifyAqeReceipt(receipt, allowlist, opts) {
+    const fingerprint = keyFingerprint(receipt.publicKeyPem);
+    if (allowlist && allowlist.size > 0) {
+        const allowed = allowlist.get(fingerprint);
+        if (!allowed)
+            return { valid: false, format: 'aqe-receipt', fingerprint, reason: 'fingerprint-not-in-allowlist' };
+        if (allowed.trim() !== receipt.publicKeyPem.trim()) {
+            return { valid: false, format: 'aqe-receipt', fingerprint, reason: 'allowlist-pem-mismatch' };
+        }
+    }
+    else if (!opts?.allowSelfSigned) {
+        // FAIL-CLOSED (qe-court finding): with no trust root, verifying against the
+        // receipt's OWN embedded key just proves internal consistency — anyone can
+        // self-sign a forged receipt. A caller must either provide an allowlist or
+        // explicitly opt into self-signed verification (e.g. a consistency check that
+        // is NOT used as authorization).
+        return { valid: false, format: 'aqe-receipt', fingerprint, reason: 'no-trust-root' };
+    }
+    const ok = verifySignature(receipt.publicKeyPem, receiptBodyString(receipt), receipt.signature);
+    return { valid: ok, format: 'aqe-receipt', fingerprint, reason: ok ? undefined : 'bad-signature' };
+}
+/**
+ * Verify a qe-harness witness bundle. Requires the signer's public key in the
+ * allowlist (platform bundles do NOT embed their PEM). Recomputes the canonical
+ * digest to detect payload tampering, then Ed25519-verifies the base64 signature
+ * over the digest string.
+ */
+export function verifyHarnessWitness(bundle, allowlist) {
+    const w = bundle.witness;
+    const fingerprint = w?.publicKeyFingerprint;
+    // Fail closed on an unexpected algorithm — never verify a non-Ed25519-declared
+    // witness as Ed25519 (qe-court finding: ambiguous alg across implementations).
+    if (w?.alg !== 'ed25519') {
+        return { valid: false, format: 'harness-witness', fingerprint, reason: 'unsupported-alg' };
+    }
+    const pem = fingerprint ? allowlist.get(fingerprint) : undefined;
+    if (!pem)
+        return { valid: false, format: 'harness-witness', fingerprint, reason: 'fingerprint-not-in-allowlist' };
+    const recomputed = canonicalDigest(bundle);
+    if (recomputed !== w.digest) {
+        return { valid: false, format: 'harness-witness', fingerprint, reason: 'digest-mismatch' };
+    }
+    try {
+        const key = createPublicKey(pem);
+        const ok = edVerify(null, Buffer.from(w.digest, 'utf8'), key, Buffer.from(w.signature, 'base64'));
+        return { valid: ok, format: 'harness-witness', fingerprint, reason: ok ? undefined : 'bad-signature' };
+    }
+    catch {
+        return { valid: false, format: 'harness-witness', fingerprint, reason: 'verify-error' };
+    }
+}
+/** Detect the artifact format and dispatch to the right verifier. */
+export function verifyWitness(artifact, allowlist = loadAllowlist()) {
+    if (artifact && typeof artifact === 'object') {
+        const o = artifact;
+        const w = o.witness;
+        if (w && typeof w === 'object' && typeof w.signature === 'string' && typeof w.publicKeyFingerprint === 'string') {
+            return verifyHarnessWitness(o, allowlist);
+        }
+        if (typeof o.signature === 'string' && typeof o.publicKeyPem === 'string' && typeof o.sealedHash === 'string') {
+            return verifyAqeReceipt(o, allowlist);
+        }
+    }
+    return { valid: false, format: 'unknown', reason: 'unrecognized-artifact' };
+}
+//# sourceMappingURL=witness-verify.js.map