@awak-app/simy-cli 0.2.3 → 0.4.0

package/src/orchestrator/audit.js

@@ -13,7 +13,7 @@ import {
   normalizeVisualReview,
 } from "./completion-contract.js";
 
-export async function auditAttempt(charter, attempt, { previousAttempt = null } = {}) {
+export async function auditAttempt(charter, attempt, { previousAttempt = null, sqm = null } = {}) {
   const checks = [];
   const addCheck = (
     id,
@@ -219,6 +219,7 @@ export async function auditAttempt(charter, attempt, { previousAttempt = null }
       ? "Implementation evidence passed local verification."
       : "Implementation evidence failed local verification.",
     checks,
+    sqm: normalizeSqmAudit(sqm),
   };
 
   return {
@@ -257,6 +258,46 @@ export async function auditAttempt(charter, attempt, { previousAttempt = null }
     release_gate: null,
     work_log_signals: [],
     work_log_interventions: [],
+    sqm: normalizeSqmAudit(sqm),
+  };
+}
+
+function normalizeSqmAudit(sqm) {
+  if (!sqm) return null;
+  return {
+    status: sqm.status || "unavailable",
+    mode: "shadow",
+    bundle: sqm.bundle || null,
+    warnings: Array.isArray(sqm.warnings) ? sqm.warnings : [],
+    findings: (Array.isArray(sqm.findings) ? sqm.findings : []).map((finding) => ({
+      finding_id: finding.finding_id,
+      module_id: finding.module_id,
+      module_version: finding.module_version,
+      rule_id: finding.rule_id,
+      severity: finding.severity,
+      file: finding.file || null,
+      line: finding.line || null,
+      side: finding.side || null,
+      evidence_hash: finding.evidence_hash,
+      bundle_id: finding.bundle_id,
+      bundle_version: finding.bundle_version,
+      bundle_digest: finding.bundle_digest,
+    })),
+    min_check: sqm.min_check ? {
+      result_digest: sqm.min_check.result_digest || null,
+      status: sqm.min_check.status || null,
+      executed_at: sqm.min_check.executed_at || null,
+    } : null,
+    proof: sqm.proof ? {
+      proof_id: sqm.proof.proof_id || null,
+      digest: sqm.proof.integrity?.digest || null,
+      outcome: sqm.proof.outcome?.status || null,
+    } : null,
+    signed_evidence: sqm.signed_evidence ? {
+      evidence_id: sqm.signed_evidence.evidence_id || null,
+      key_id: sqm.signed_evidence.signer?.key_id || null,
+      algorithm: sqm.signed_evidence.integrity?.algorithm || null,
+    } : null,
   };
 }
 

package/src/orchestrator/loop.js

@@ -14,6 +14,7 @@ export async function runCodingLoop({
   executeAttempt,
   executeIndependentAudit,
   collectEvidence,
+  checkSqm = null,
   onUpdate,
   humanGuidance = "",
   resume = false,
@@ -127,6 +128,7 @@ export async function runCodingLoop({
     });
     await publish(snapshot, "collecting_evidence", onUpdate);
     attempt.observed_evidence = await safeEvidence(collectEvidence, attempt);
+    attempt.sqm = await safeSqm(checkSqm, attempt);
     if (shouldStop()) return stopCodingLoop(snapshot, onUpdate);
 
     appendEvent(snapshot, "auditing", `Verifying local evidence for attempt ${attemptNumber}.`, {
@@ -140,7 +142,10 @@ export async function runCodingLoop({
         attempt.observed_evidence?.github?.available === true,
     });
     await publish(snapshot, "auditing", onUpdate);
-    attempt.audit = await auditAttempt(snapshot.charter, attempt, { previousAttempt });
+    attempt.audit = await auditAttempt(snapshot.charter, attempt, {
+      previousAttempt,
+      sqm: attempt.sqm,
+    });
     if (shouldStop()) return stopCodingLoop(snapshot, onUpdate);
     attempt.implementation_gate = attempt.audit.implementation_gate;
     snapshot.attempts.push(attempt);
@@ -212,8 +217,12 @@ export async function runCodingLoop({
 
     // Re-collect after the read-only auditor to catch any mutated HEAD or working tree.
     attempt.observed_evidence = await safeEvidence(collectEvidence, attempt);
+    attempt.sqm = await safeSqm(checkSqm, attempt, attempt.sqm);
     if (shouldStop()) return stopCodingLoop(snapshot, onUpdate);
-    attempt.audit = await auditAttempt(snapshot.charter, attempt, { previousAttempt });
+    attempt.audit = await auditAttempt(snapshot.charter, attempt, {
+      previousAttempt,
+      sqm: attempt.sqm,
+    });
     if (shouldStop()) return stopCodingLoop(snapshot, onUpdate);
     attempt.implementation_gate = attempt.audit.implementation_gate;
 
@@ -267,7 +276,7 @@ async function stopCodingLoop(snapshot, onUpdate) {
   return snapshot;
 }
 
-export async function recheckPrReadiness({ snapshot, collectEvidence, onUpdate }) {
+export async function recheckPrReadiness({ snapshot, collectEvidence, checkSqm = null, onUpdate }) {
   const attempt = snapshot.attempts.at(-1);
   if (!attempt || !attempt.audit?.passed || !attempt.independent_audit?.passed) return snapshot;
   appendEvent(snapshot, "checking_pr", "Refreshing GitHub review and CI evidence.", {
@@ -275,8 +284,10 @@ export async function recheckPrReadiness({ snapshot, collectEvidence, onUpdate }
   });
   await publish(snapshot, "checking_pr", onUpdate);
   attempt.observed_evidence = await safeEvidence(collectEvidence, attempt);
+  attempt.sqm = await safeSqm(checkSqm, attempt, attempt.sqm, "full");
   attempt.audit = await auditAttempt(snapshot.charter, attempt, {
     previousAttempt: snapshot.attempts.at(-2) ?? null,
+    sqm: attempt.sqm,
   });
   snapshot.implementation_gate_passed = attempt.audit.passed;
   attempt.pr_readiness = evaluatePrReadiness(snapshot.charter, attempt);
@@ -352,6 +363,21 @@ async function safeEvidence(collector, attempt) {
   }
 }
 
+async function safeSqm(checker, attempt, previous = null, phase = "min") {
+  if (!checker) return previous;
+  try {
+    return await checker(attempt, { phase });
+  } catch (error) {
+    return {
+      status: "unavailable",
+      mode: "shadow",
+      bundle: null,
+      findings: [],
+      warnings: [error instanceof Error ? error.message : "SQM shadow check failed."],
+    };
+  }
+}
+
 function unavailableEvidence(error) {
   return {
     collected_at: new Date().toISOString(),

package/src/repository-inventory.js

@@ -1,5 +1,12 @@
 import { execFile } from "node:child_process";
-import { mkdir, readFile, readdir, realpath, writeFile } from "node:fs/promises";
+import {
+  lstat,
+  mkdir,
+  readFile,
+  readdir,
+  realpath,
+  writeFile,
+} from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { promisify } from "node:util";
@@ -152,6 +159,35 @@ export function findRepository(inventory, repository) {
   );
 }
 
+export async function verifyRepositoryIdentity(entry, expectedRepository) {
+  const expected = normalizeGitHubRemote(expectedRepository)?.toLowerCase();
+  const localPath = resolve(String(entry?.local_path || ""));
+  if (!expected || !localPath) return null;
+  try {
+    const details = await lstat(localPath);
+    if (!details.isDirectory() || details.isSymbolicLink()) return null;
+    const canonicalPath = await realpath(localPath);
+    const [{ stdout: root }, { stdout: remote }] = await Promise.all([
+      execFileAsync("git", ["rev-parse", "--show-toplevel"], { cwd: canonicalPath }),
+      execFileAsync("git", ["remote", "get-url", "origin"], { cwd: canonicalPath }),
+    ]);
+    const canonicalRoot = await realpath(resolve(String(root || "").trim()));
+    if (
+      canonicalRoot !== canonicalPath ||
+      normalizeGitHubRemote(remote)?.toLowerCase() !== expected
+    ) {
+      return null;
+    }
+    return {
+      ...entry,
+      repository: normalizeGitHubRemote(remote),
+      local_path: canonicalPath,
+    };
+  } catch {
+    return null;
+  }
+}
+
 async function inspectGitRepository(directory) {
   try {
     const [{ stdout: root }, { stdout: remote }, { stdout: branch }] = await Promise.all([

package/src/runner.js

@@ -40,6 +40,8 @@ import {
 import { LocalRunRegistry } from "./run-registry.js";
 import { webApiHeaders, webApiUrl } from "./web-api.js";
 import { normalizeGitHubRemote } from "./workspace-context.js";
+import { CLI_VERSION } from "./cli-contract.js";
+import { createSqmChecker } from "./sqm/index.js";
 
 const execFileAsync = promisify(execFile);
 const MAX_LOCAL_LOG_LINES = 1_000;
@@ -543,6 +545,20 @@ async function runLocalCodingRun(
         attempt,
         repositoryPath,
       }));
+  const sqmChecker =
+    run.sqmChecker ||
+    createSqmChecker({
+      cwd: repositoryPath,
+      baseBranch: run.snapshot.charter.base_branch,
+      cliVersion: CLI_VERSION,
+      token: run.session?.token,
+      endpoint: sqmBundleEndpoint(run.session),
+      evidenceEndpoint: sqmEvidenceEndpoint(run.session),
+      accountId: run.session?.account_id || run.session?.auth_user_id || run.session?.device_id,
+      organizationId: run.session?.organization_id || run.session?.org_id,
+      deviceId: run.session?.device_id,
+    });
+  run.sqmChecker = sqmChecker;
 
   try {
     await runCodingLoop({
@@ -550,6 +566,7 @@ async function runLocalCodingRun(
       executeAttempt: executor,
       executeIndependentAudit: independentAuditor,
       collectEvidence: evidenceCollector,
+      checkSqm: sqmChecker,
       humanGuidance,
       resume,
       shouldStop: () => run.stopRequested,
@@ -601,9 +618,24 @@ export async function recheckLocalCodingRun(run, { collectEvidence } = {}) {
         attempt,
         repositoryPath,
       }));
+  const sqmChecker =
+    run.sqmChecker ||
+    createSqmChecker({
+      cwd: repositoryPath,
+      baseBranch: run.snapshot.charter.base_branch,
+      cliVersion: CLI_VERSION,
+      token: run.session?.token,
+      endpoint: sqmBundleEndpoint(run.session),
+      evidenceEndpoint: sqmEvidenceEndpoint(run.session),
+      accountId: run.session?.account_id || run.session?.auth_user_id || run.session?.device_id,
+      organizationId: run.session?.organization_id || run.session?.org_id,
+      deviceId: run.session?.device_id,
+    });
+  run.sqmChecker = sqmChecker;
   await recheckPrReadiness({
     snapshot: run.snapshot,
     collectEvidence: evidenceCollector,
+    checkSqm: sqmChecker,
     onUpdate: async (snapshot) => {
       run.snapshot = snapshot;
       await updateRun(run, snapshot.state);
@@ -612,6 +644,18 @@ export async function recheckLocalCodingRun(run, { collectEvidence } = {}) {
   return run.snapshot;
 }
 
+function sqmBundleEndpoint(session) {
+  if (process.env.SIMY_SQM_BUNDLE_URL?.trim()) return process.env.SIMY_SQM_BUNDLE_URL.trim();
+  if (!session?.api_base_url) return undefined;
+  return new URL("sqm/knowledge-bundle", session.api_base_url).href;
+}
+
+function sqmEvidenceEndpoint(session) {
+  if (process.env.SIMY_SQM_EVIDENCE_URL?.trim()) return process.env.SIMY_SQM_EVIDENCE_URL.trim();
+  if (!session?.api_base_url) return undefined;
+  return new URL("sqm/run-evidence", session.api_base_url).href;
+}
+
 async function executeProcessAttempt({
   backend,
   instruction,

package/src/shutdown.js

@@ -0,0 +1,63 @@
+const SHUTDOWN_SIGNALS = ["SIGINT", "SIGTERM"];
+
+export function createAgentShutdown(agent) {
+  let shutdownPromise = null;
+  return () => {
+    if (!shutdownPromise) shutdownPromise = closeAgent(agent);
+    return shutdownPromise;
+  };
+}
+
+export async function closeAgent(agent) {
+  const serverClose = beginServerClose(agent?.server);
+  let shutdownError = null;
+  try {
+    await agent?.shutdown?.();
+  } catch (error) {
+    shutdownError = error;
+  } finally {
+    // server.close() stops new connections immediately, but its callback waits
+    // for active SSE and other long-lived requests. Drain Provider work and its
+    // final durable status first, then release those remaining connections.
+    agent?.server?.closeAllConnections?.();
+  }
+  await serverClose;
+  if (shutdownError) throw shutdownError;
+}
+
+export function installAgentShutdownSignalHandlers({
+  signalSource = process,
+  shutdown,
+  exit = (code) => process.exit(code),
+  reportError = (error) => console.error(error instanceof Error ? error.message : String(error)),
+} = {}) {
+  if (typeof shutdown !== "function") throw new TypeError("shutdown is required");
+  const handlers = new Map();
+  for (const signal of SHUTDOWN_SIGNALS) {
+    const handler = () => {
+      void shutdown()
+        .then(() => exit(0))
+        .catch((error) => {
+          reportError(error);
+          exit(1);
+        });
+    };
+    handlers.set(signal, handler);
+    signalSource.once(signal, handler);
+  }
+  return () => {
+    for (const [signal, handler] of handlers) {
+      signalSource.off(signal, handler);
+    }
+  };
+}
+
+function beginServerClose(server) {
+  if (!server?.listening) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    server.close((error) => {
+      if (error) reject(error);
+      else resolve();
+    });
+  });
+}

package/src/sqm/bundle-store.js

@@ -0,0 +1,249 @@
+import { createHash, createPublicKey } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+
+import { verifyBundleIntegrity } from "./canonical.js";
+import { validateKnowledgeBundle } from "./validation.js";
+
+const DEFAULT_TTL_MS = 5 * 60 * 1000;
+export const SQM_BUNDLE_FETCH_TIMEOUT_MS = 15_000;
+
+export async function loadKnowledgeBundle({
+  repository,
+  cliVersion,
+  endpoint = process.env.SIMY_SQM_BUNDLE_URL,
+  token = process.env.SIMY_SQM_TOKEN || process.env.SIMY_ACCESS_TOKEN,
+  accountId = process.env.SIMY_SQM_ACCOUNT_ID || (token ? `token:${createHash("sha256").update(token).digest("hex")}` : "anonymous"),
+  organizationId = process.env.SIMY_SQM_ORGANIZATION_ID,
+  cacheRoot = process.env.SIMY_SQM_CACHE_DIR || path.join(process.env.SIMY_HOME?.trim() || path.join(homedir(), ".simy"), "sqm"),
+  ttlMs = numberEnv("SIMY_SQM_CACHE_TTL_MS", DEFAULT_TTL_MS),
+  offline = false,
+  refresh = false,
+  fetchImpl = globalThis.fetch,
+  now = Date.now(),
+  publicKeys = publicKeysFromEnvironment(),
+}) {
+  if (!organizationId) {
+    return result(null, ["SQM organization identity is unavailable; shadow checks were skipped."], "unavailable");
+  }
+  const cacheIdentity = normalizedCacheIdentity({ endpoint, accountId, organizationId, repository });
+  const location = cacheLocation(cacheRoot, cacheIdentity);
+  const validation = { cliVersion, publicKeys, organizationId };
+  const cached = await readVerifiedCache(location, validation, cacheIdentity);
+  const fresh =
+    cached &&
+    now - cached.fetchedAt < ttlMs &&
+    Date.parse(cached.bundle.expires_at) > now;
+  if (!offline && endpoint && (!fresh || refresh)) {
+    try {
+      const fetched = await fetchBundle({ endpoint, repository, cliVersion, token, organizationId, etag: cached?.etag, fetchImpl });
+      if (fetched.notModified) {
+        if (!cached) throw new Error("SQM Cloud returned 304 without a verified local bundle.");
+        if (Date.parse(cached.bundle.expires_at) <= now) throw nonFallbackError("SQM Cloud returned 304 for an expired knowledge bundle.");
+        await writeMetadata(location, { ...cached.metadata, fetched_at: new Date(now).toISOString(), etag: fetched.etag || cached.etag });
+        return result(cached.bundle, [], "cache_revalidated");
+      }
+      const discoveredTrust = signingTrustForFetch({
+        bundle: fetched.bundle,
+        endpoint,
+        publicKeys,
+        signingKeyId: fetched.signingKeyId,
+        signingPublicKey: fetched.signingPublicKey,
+      });
+      const bundle = verifyAndValidate(fetched.bundle, {
+        ...validation,
+        publicKeys: discoveredTrust.publicKeys,
+      });
+      if (Date.parse(bundle.expires_at) <= now) {
+        throw nonFallbackError("SQM Cloud returned an expired knowledge bundle.");
+      }
+      if (fetched.etag && unquote(fetched.etag) !== bundle.integrity.digest) throw nonFallbackError("SQM response ETag does not match the bundle digest.");
+      await writeCache(location, bundle, {
+        ...cacheIdentity,
+        fetched_at: new Date(now).toISOString(),
+        etag: fetched.etag || `\"${bundle.integrity.digest}\"`,
+        signing_key_id: discoveredTrust.signingKeyId,
+        signing_public_key: discoveredTrust.signingPublicKey,
+      });
+      return result(bundle, [], "cloud");
+    } catch (error) {
+      if (error?.fallbackAllowed !== false && cached && Date.parse(cached.bundle.expires_at) > now) return result(cached.bundle, [`SQM Cloud unavailable; using last verified bundle: ${message(error)}`], "stale_cache");
+      return result(null, [`SQM knowledge could not be used; shadow checks were skipped: ${message(error)}`], "unavailable");
+    }
+  }
+  if (cached) {
+    if (Date.parse(cached.bundle.expires_at) <= now) return result(null, ["The cached SQM knowledge bundle is expired; shadow checks were skipped."], "unavailable");
+    const warnings = [];
+    if (offline) warnings.push("SQM is offline; using the last verified knowledge bundle.");
+    else if (!endpoint) warnings.push("SQM Cloud endpoint is not configured; using the last verified knowledge bundle.");
+    return result(cached.bundle, warnings, fresh ? "cache" : "stale_cache");
+  }
+  const reason = offline ? "offline mode" : "SQM Cloud endpoint is not configured";
+  return result(null, [`SQM has no verified cache (${reason}); shadow checks were skipped.`], "unavailable");
+}
+
+export function verifyAndValidate(bundle, { cliVersion, publicKeys, organizationId } = {}) {
+  try { validateKnowledgeBundle(bundle, { cliVersion }); } catch (error) { throw nonFallbackError(message(error), error); }
+  if (organizationId && bundle.organization_id !== organizationId) throw nonFallbackError(`SQM bundle organization mismatch: expected ${organizationId}.`);
+  for (const module of bundle.modules) {
+    if (module.scope.visibility === "organization" && module.scope.organization_id !== bundle.organization_id) throw nonFallbackError(`SQM module ${module.id} is scoped to a different organization.`);
+  }
+  const keyId = bundle.integrity.key_id;
+  const key = publicKeys.get(keyId);
+  if (!key) throw nonFallbackError(`No trusted SQM public key is configured for ${keyId}.`);
+  try { verifyBundleIntegrity(bundle, key); } catch (error) { throw nonFallbackError(message(error), error); }
+  return bundle;
+}
+
+export function publicKeysFromEnvironment(env = process.env) {
+  const keys = new Map();
+  if (env.SIMY_SQM_PUBLIC_KEYS_JSON) {
+    let parsed;
+    try { parsed = JSON.parse(env.SIMY_SQM_PUBLIC_KEYS_JSON); } catch { throw new Error("SIMY_SQM_PUBLIC_KEYS_JSON is not valid JSON."); }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("SIMY_SQM_PUBLIC_KEYS_JSON must be an object keyed by key ID.");
+    for (const [id, value] of Object.entries(parsed)) keys.set(id, parsePublicKey(value));
+  }
+  if (env.SIMY_SQM_PUBLIC_KEY && env.SIMY_SQM_KEY_ID) keys.set(env.SIMY_SQM_KEY_ID, parsePublicKey(env.SIMY_SQM_PUBLIC_KEY));
+  return keys;
+}
+
+function parsePublicKey(value) {
+  const text = String(value || "").replace(/\\n/g, "\n").trim();
+  if (text.startsWith("-----BEGIN")) return createPublicKey(text);
+  const raw = Buffer.from(text, "base64");
+  if (raw.length === 32) {
+    const prefix = Buffer.from("302a300506032b6570032100", "hex");
+    return createPublicKey({ key: Buffer.concat([prefix, raw]), format: "der", type: "spki" });
+  }
+  return createPublicKey({ key: raw, format: "der", type: "spki" });
+}
+
+function signingTrustForFetch({ bundle, endpoint, publicKeys, signingKeyId, signingPublicKey }) {
+  const keyId = bundle?.integrity?.key_id;
+  if (publicKeys.has(keyId)) {
+    return { publicKeys, signingKeyId: null, signingPublicKey: null };
+  }
+  if (!trustedDiscoveryEndpoint(endpoint)) {
+    throw nonFallbackError("SQM signing-key discovery requires authenticated HTTPS or loopback.");
+  }
+  if (!signingKeyId || signingKeyId !== keyId || !signingPublicKey) {
+    throw nonFallbackError(`SQM Cloud did not provide the trusted public key for ${keyId}.`);
+  }
+  const discovered = new Map(publicKeys);
+  try {
+    discovered.set(keyId, parsePublicKey(signingPublicKey));
+  } catch (error) {
+    throw nonFallbackError(`SQM Cloud returned an invalid public key for ${keyId}.`, error);
+  }
+  return {
+    publicKeys: discovered,
+    signingKeyId,
+    signingPublicKey: String(signingPublicKey).trim(),
+  };
+}
+
+function trustedDiscoveryEndpoint(endpoint) {
+  const url = new URL(endpoint);
+  return url.protocol === "https:" ||
+    (url.protocol === "http:" && ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname));
+}
+
+async function fetchBundle({ endpoint, repository, cliVersion, token, organizationId, etag, fetchImpl }) {
+  const url = new URL(endpoint);
+  url.searchParams.set("repository", repository);
+  url.searchParams.set("cli_version", cliVersion);
+  const headers = { Accept: "application/json" };
+  if (token) headers.Authorization = `Bearer ${token}`;
+  if (organizationId) headers["x-simy-org-id"] = organizationId;
+  if (etag) headers["If-None-Match"] = etag;
+  const response = await fetchImpl(url, {
+    headers,
+    signal: AbortSignal.timeout(SQM_BUNDLE_FETCH_TIMEOUT_MS),
+  });
+  const responseEtag = response.headers?.get?.("etag") || null;
+  const signingKeyId = response.headers?.get?.("x-simy-sqm-key-id") || null;
+  const signingPublicKey = response.headers?.get?.("x-simy-sqm-public-key") || null;
+  if (response.status === 304) {
+    return { notModified: true, etag: responseEtag, signingKeyId, signingPublicKey };
+  }
+  if (!response.ok) {
+    const body = await response.text().catch(() => "");
+    const error = new Error(`SQM Cloud returned HTTP ${response.status}${body ? `: ${body.slice(0, 300)}` : ""}.`);
+    error.fallbackAllowed = response.status >= 500 && response.status <= 599;
+    throw error;
+  }
+  try {
+    return {
+      notModified: false,
+      etag: responseEtag,
+      signingKeyId,
+      signingPublicKey,
+      bundle: await response.json(),
+    };
+  } catch (error) {
+    throw nonFallbackError("SQM Cloud returned an invalid JSON knowledge bundle.", error);
+  }
+}
+
+async function readVerifiedCache(location, options, identity) {
+  try {
+    const [bundleRaw, metadataRaw] = await Promise.all([readFile(location.bundle, "utf8"), readFile(location.metadata, "utf8")]);
+    const metadata = JSON.parse(metadataRaw);
+    for (const key of ["endpoint", "account_id", "organization_id", "repository"]) if (metadata[key] !== identity[key]) throw new Error("SQM cache identity does not match the current tenant context.");
+    const publicKeys = new Map(options.publicKeys);
+    if (metadata.signing_key_id && metadata.signing_public_key && !publicKeys.has(metadata.signing_key_id)) {
+      publicKeys.set(metadata.signing_key_id, parsePublicKey(metadata.signing_public_key));
+    }
+    const bundle = verifyAndValidate(JSON.parse(bundleRaw), { ...options, publicKeys });
+    if (metadata.digest !== bundle.integrity.digest || metadata.bundle_id !== bundle.bundle_id || metadata.version !== bundle.version) throw new Error("SQM cache metadata does not match its bundle.");
+    if (metadata.signing_key_id && metadata.signing_key_id !== bundle.integrity.key_id) throw new Error("SQM cache signing key does not match its bundle.");
+    return { bundle, metadata, etag: metadata.etag || null, fetchedAt: Date.parse(metadata.fetched_at) || 0 };
+  } catch {
+    return null;
+  }
+}
+
+async function writeCache(location, bundle, metadata) {
+  await mkdir(location.directory, { recursive: true, mode: 0o700 });
+  await atomicWrite(location.bundle, `${JSON.stringify(bundle)}\n`);
+  await writeMetadata(location, { ...metadata, bundle_id: bundle.bundle_id, version: bundle.version, digest: bundle.integrity.digest, verified_at: new Date().toISOString() });
+}
+
+async function writeMetadata(location, metadata) {
+  await mkdir(location.directory, { recursive: true, mode: 0o700 });
+  await atomicWrite(location.metadata, `${JSON.stringify(metadata)}\n`);
+}
+
+async function atomicWrite(target, content) {
+  const temporary = `${target}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;
+  await writeFile(temporary, content, { encoding: "utf8", mode: 0o600 });
+  await rename(temporary, target);
+}
+
+function cacheLocation(root, identity) {
+  const id = createHash("sha256").update(JSON.stringify(identity)).digest("hex");
+  const directory = path.join(root, id);
+  return { directory, bundle: path.join(directory, "bundle.json"), metadata: path.join(directory, "metadata.json") };
+}
+
+function normalizedCacheIdentity({ endpoint, accountId, organizationId, repository }) {
+  let normalizedEndpoint = "unconfigured";
+  if (endpoint) {
+    const url = new URL(endpoint);
+    url.hash = "";
+    normalizedEndpoint = url.href;
+  }
+  return { endpoint: normalizedEndpoint, account_id: String(accountId || "anonymous"), organization_id: organizationId ? String(organizationId) : null, repository: String(repository).toLowerCase() };
+}
+
+function nonFallbackError(message, cause) {
+  const error = new Error(message, { cause });
+  error.fallbackAllowed = false;
+  return error;
+}
+
+function result(bundle, warnings, source) { return { bundle, warnings, source }; }
+function message(error) { return error instanceof Error ? error.message : String(error); }
+function numberEnv(name, fallback) { const parsed = Number(process.env[name]); return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback; }
+function unquote(value) { return String(value).replace(/^W\//, "").replace(/^\"|\"$/g, ""); }

package/src/sqm/canonical.js

@@ -0,0 +1,45 @@
+import { createHash, verify } from "node:crypto";
+
+export function canonicalize(value) {
+  if (value === null || typeof value === "boolean" || typeof value === "string") {
+    return JSON.stringify(value);
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new TypeError("JCS does not allow non-finite numbers.");
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) return `[${value.map(canonicalize).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${canonicalize(value[key])}`)
+      .join(",")}}`;
+  }
+  throw new TypeError(`JCS does not allow ${typeof value} values.`);
+}
+
+export function bundlePayloadBytes(bundle) {
+  const { integrity: _integrity, ...payload } = bundle;
+  return Buffer.from(canonicalize(payload), "utf8");
+}
+
+export function bundleDigest(bundle) {
+  return createHash("sha256").update(bundlePayloadBytes(bundle)).digest();
+}
+
+export function verifyBundleIntegrity(bundle, publicKey) {
+  const digest = bundleDigest(bundle);
+  const expected = `sha256:${digest.toString("hex")}`;
+  if (bundle?.integrity?.digest !== expected) {
+    throw new Error(`SQM bundle digest mismatch: expected ${expected}.`);
+  }
+  const encoded = String(bundle?.integrity?.signature || "");
+  if (!/^[A-Za-z0-9+/]+$/.test(encoded)) {
+    throw new Error("SQM bundle signature is not valid base64.");
+  }
+  const signature = Buffer.from(encoded, "base64");
+  if (signature.length !== 64 || !verify(null, digest, publicKey, signature)) {
+    throw new Error("SQM bundle Ed25519 signature verification failed.");
+  }
+  return expected;
+}