@compr/opscontext-mcp 2.1.1 → 2.1.3

package/dist/community-sync.js

@@ -0,0 +1,506 @@
+/**
+ * community-sync.ts — fetch & cache community-contributed learnings.
+ *
+ * Two tiers:
+ *   A) Public  — raw.githubusercontent.com (no auth, ETag cached)
+ *   B) Pro     — api.compr.ch (license-token auth, server-signed payload)
+ *
+ * Both tiers produce CommunityRule records that share the local store at
+ * ~/.contextengine/community-learnings.json. At search-init time the
+ * MCP server merges these into the same chunk pipeline as the local
+ * Learnings Store so they surface inside search_context with a
+ * "(community)" badge.
+ *
+ * Auth shape for Tier B matches /heartbeat exactly (see activation.ts):
+ *   POST { license_token, machine_id }
+ *
+ * Design constraints:
+ *   - Node built-in `https` only (no fetch wrapper deps)
+ *   - Network failures NEVER crash search — fall back to cached store
+ *   - Tier B is best-effort; on 401 we log + return zero, don't throw
+ *   - The signed payload from Tier B is verified before merge using the
+ *     existing Ed25519 verifyLicenseSignature() helper
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { createHash } from "crypto";
+import * as https from "https";
+import { URL } from "url";
+import { safeAppend } from "./audit.js";
+import { verifyLicenseSignature, } from "./license-sig.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+export const TIER_A_URL = "https://raw.githubusercontent.com/FASTPROD/opscontext-community-rules/main/rules.json";
+export const TIER_B_URL = "https://api.compr.ch/contextengine/community-rules/fetch";
+export const STORE_PATH = join(homedir(), ".contextengine", "community-learnings.json");
+const STORE_DIR = join(homedir(), ".contextengine");
+// ---------------------------------------------------------------------------
+// Machine fingerprint — duplicated from activation.ts so this module has
+// zero internal coupling. Both must produce identical output; if you
+// change one, change both.
+// ---------------------------------------------------------------------------
+export function getMachineId() {
+    const components = [
+        process.platform,
+        process.arch,
+        homedir().split("/").slice(0, 3).join("/"),
+        process.env.USER || process.env.USERNAME || "unknown",
+    ];
+    return createHash("sha256")
+        .update(components.join("|"))
+        .digest("hex")
+        .slice(0, 16);
+}
+// ---------------------------------------------------------------------------
+// Store I/O
+// ---------------------------------------------------------------------------
+function ensureDir() {
+    if (!existsSync(STORE_DIR)) {
+        mkdirSync(STORE_DIR, { recursive: true });
+    }
+}
+function emptyStore() {
+    return {
+        version: 1,
+        fetched_at: new Date(0).toISOString(),
+        rules: [],
+    };
+}
+export function loadCommunityStore() {
+    if (!existsSync(STORE_PATH))
+        return emptyStore();
+    try {
+        const raw = readFileSync(STORE_PATH, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (!parsed ||
+            typeof parsed !== "object" ||
+            parsed.version !== 1 ||
+            !Array.isArray(parsed.rules)) {
+            return emptyStore();
+        }
+        return parsed;
+    }
+    catch {
+        return emptyStore();
+    }
+}
+function saveCommunityStore(store) {
+    ensureDir();
+    writeFileSync(STORE_PATH, JSON.stringify(store, null, 2));
+}
+export function httpRequest(url, opts = {}) {
+    return new Promise((resolve, reject) => {
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch (e) {
+            reject(e);
+            return;
+        }
+        const requestFn = opts.requestFn || https.request;
+        const reqOpts = {
+            method: opts.method || "GET",
+            hostname: parsed.hostname,
+            port: parsed.port || 443,
+            path: parsed.pathname + parsed.search,
+            headers: opts.headers || {},
+        };
+        const req = requestFn(reqOpts, (res) => {
+            const chunks = [];
+            res.on("data", (chunk) => chunks.push(chunk));
+            res.on("end", () => {
+                resolve({
+                    statusCode: res.statusCode || 0,
+                    headers: res.headers,
+                    body: Buffer.concat(chunks).toString("utf-8"),
+                });
+            });
+            res.on("error", reject);
+        });
+        req.on("error", reject);
+        if (opts.body)
+            req.write(opts.body);
+        req.end();
+    });
+}
+// Test seam — community-sync.test.ts sets these to intercept network I/O
+// without monkey-patching globals.
+let _httpForTest = null;
+export function __setHttpForTesting(fn) {
+    _httpForTest = fn;
+}
+function http(url, opts = {}) {
+    if (_httpForTest)
+        return _httpForTest(url, opts);
+    return httpRequest(url, opts);
+}
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+function isValidRuleShape(r) {
+    if (!r || typeof r !== "object")
+        return false;
+    const rec = r;
+    return (typeof rec.id === "string" &&
+        typeof rec.category === "string" &&
+        typeof rec.rule === "string" &&
+        rec.rule.length >= 10 &&
+        typeof rec.context === "string" &&
+        Array.isArray(rec.tags) &&
+        rec.tags.every((t) => typeof t === "string"));
+}
+function normalizeIncoming(source, rawRules) {
+    const now = new Date().toISOString();
+    const out = [];
+    for (const r of rawRules) {
+        if (!isValidRuleShape(r))
+            continue;
+        const rec = r;
+        out.push({
+            id: rec.id,
+            source,
+            category: rec.category,
+            rule: rec.rule,
+            context: rec.context,
+            tags: rec.tags,
+            project_cluster: typeof rec.project_cluster === "string"
+                ? rec.project_cluster
+                : undefined,
+            fetched_at: now,
+        });
+    }
+    return out;
+}
+/**
+ * Replace all rules from a given source with the freshly-fetched set.
+ * (Rules from the *other* source are preserved.)
+ */
+function mergeRules(store, source, freshRules) {
+    const keep = store.rules.filter((r) => r.source !== source);
+    return {
+        ...store,
+        fetched_at: new Date().toISOString(),
+        rules: [...keep, ...freshRules],
+    };
+}
+// ---------------------------------------------------------------------------
+// Tier A — public GitHub-hosted rules
+// ---------------------------------------------------------------------------
+export async function syncTierA(opts = {}) {
+    const store = loadCommunityStore();
+    const headers = {
+        "User-Agent": "opscontext-community-sync/1",
+        Accept: "application/json",
+    };
+    if (!opts.force && store.source_tier_a_etag) {
+        headers["If-None-Match"] = store.source_tier_a_etag;
+    }
+    let res;
+    try {
+        res = await http(TIER_A_URL, { method: "GET", headers });
+    }
+    catch (e) {
+        // Network failure — fall back to cache, don't crash.
+        process.stderr.write(`[community-sync] Tier A fetch failed (${e instanceof Error ? e.message : String(e)}); using cached store.\n`);
+        safeAppend("community.sync_error", {
+            tier: "A",
+            reason: e instanceof Error ? e.message : String(e),
+        });
+        return { fetched: 0, cached: true };
+    }
+    if (res.statusCode === 304) {
+        return { fetched: 0, cached: true };
+    }
+    if (res.statusCode !== 200) {
+        process.stderr.write(`[community-sync] Tier A unexpected status ${res.statusCode}; using cached store.\n`);
+        safeAppend("community.sync_error", {
+            tier: "A",
+            status: res.statusCode,
+        });
+        return { fetched: 0, cached: true };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(res.body);
+    }
+    catch {
+        process.stderr.write(`[community-sync] Tier A JSON parse failed; using cache.\n`);
+        safeAppend("community.sync_error", { tier: "A", reason: "json_parse" });
+        return { fetched: 0, cached: true };
+    }
+    const rawRules = Array.isArray(parsed)
+        ? parsed
+        : Array.isArray(parsed?.rules)
+            ? parsed.rules
+            : [];
+    const fresh = normalizeIncoming("tier-A-public", rawRules);
+    const merged = mergeRules(store, "tier-A-public", fresh);
+    const etag = readEtag(res.headers);
+    if (etag)
+        merged.source_tier_a_etag = etag;
+    saveCommunityStore(merged);
+    safeAppend("community.sync_ok", { tier: "A", fetched: fresh.length });
+    return { fetched: fresh.length, cached: false };
+}
+function readEtag(headers) {
+    const v = headers["etag"] || headers["ETag"] || headers["Etag"];
+    if (!v)
+        return null;
+    if (Array.isArray(v))
+        return v[0];
+    return v;
+}
+export async function syncTierB(licenseToken, opts = {}) {
+    if (!licenseToken) {
+        process.stderr.write(`[community-sync] Tier B skipped: no license token provided.\n`);
+        return { fetched: 0, cached: false };
+    }
+    const store = loadCommunityStore();
+    const headers = {
+        "User-Agent": "opscontext-community-sync/1",
+        "Content-Type": "application/json",
+        Accept: "application/json",
+    };
+    if (!opts.force && store.source_tier_b_etag) {
+        headers["If-None-Match"] = store.source_tier_b_etag;
+    }
+    const body = JSON.stringify({
+        license_token: licenseToken,
+        machine_id: getMachineId(),
+    });
+    let res;
+    try {
+        res = await http(TIER_B_URL, { method: "POST", headers, body });
+    }
+    catch (e) {
+        process.stderr.write(`[community-sync] Tier B fetch failed (${e instanceof Error ? e.message : String(e)}); using cached store.\n`);
+        safeAppend("community.sync_error", {
+            tier: "B",
+            reason: e instanceof Error ? e.message : String(e),
+        });
+        return { fetched: 0, cached: true };
+    }
+    if (res.statusCode === 304) {
+        return { fetched: 0, cached: true };
+    }
+    if (res.statusCode === 401 || res.statusCode === 403) {
+        process.stderr.write(`[community-sync] Tier B auth rejected (HTTP ${res.statusCode}). ` +
+            `Subscription may have expired — visit https://api.compr.ch/contextengine/pricing to renew. ` +
+            `Continuing with cached community store.\n`);
+        safeAppend("community.sync_error", {
+            tier: "B",
+            status: res.statusCode,
+            reason: "auth_rejected",
+        });
+        return { fetched: 0, cached: false };
+    }
+    if (res.statusCode !== 200) {
+        process.stderr.write(`[community-sync] Tier B unexpected status ${res.statusCode}; using cached store.\n`);
+        safeAppend("community.sync_error", {
+            tier: "B",
+            status: res.statusCode,
+        });
+        return { fetched: 0, cached: true };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(res.body);
+    }
+    catch {
+        process.stderr.write(`[community-sync] Tier B JSON parse failed; using cache.\n`);
+        safeAppend("community.sync_error", { tier: "B", reason: "json_parse" });
+        return { fetched: 0, cached: true };
+    }
+    if (!parsed || !Array.isArray(parsed.rules) || !parsed.signature) {
+        process.stderr.write(`[community-sync] Tier B payload missing rules or signature; rejecting.\n`);
+        safeAppend("community.sync_error", { tier: "B", reason: "shape_invalid" });
+        return { fetched: 0, cached: true };
+    }
+    // Verify the server's signature on its signable-payload field. We reuse
+    // verifyLicenseSignature() rather than inventing a new envelope — the
+    // server signs the same SignableLicensePayload shape it already signs
+    // for /activate, so the public key + canonicalPayload are byte-identical.
+    const verify = verifyLicenseSignature({
+        ...parsed.signature_payload,
+        signature: parsed.signature,
+    });
+    if (!verify.ok) {
+        process.stderr.write(`[community-sync] Tier B signature rejected (${verify.reason}); discarding fetched rules.\n`);
+        safeAppend("community.sync_error", {
+            tier: "B",
+            reason: "signature_invalid",
+            detail: verify.reason,
+        });
+        return { fetched: 0, cached: true };
+    }
+    // 🔒 LOCKED [COMMUNITY-SYNC-REPLAY-GUARD] — 2026-06-25
+    // ⛔ NEVER trust a valid signature alone — also bind it to THIS request.
+    //   The signed payload must reference OUR license token + OUR machine_id +
+    //   a fresh timestamp. Without these checks, a Tier B response captured
+    //   by any past PRO subscriber could be replayed against any other
+    //   subscriber's machine indefinitely.
+    // WHY: Round-1 verifier of workflow wy5qwwp1q flagged "no signature_payload
+    //   binding — signed Tier-B blobs are replayable forever" as a blocking
+    //   safety gap. This guard closes it.
+    // FIX: If the server's payload schema changes (e.g. binds something other
+    //   than license-token to signed responses), update BOTH the server's
+    //   signResponsePayload AND this client guard in the same commit.
+    const machineId = getMachineId();
+    const sigP = parsed.signature_payload;
+    if (sigP.key !== licenseToken) {
+        process.stderr.write(`[community-sync] Tier B signature payload license-token mismatch; replay or wrong-customer response. Rejecting.\n`);
+        safeAppend("community.sync_error", {
+            tier: "B",
+            reason: "replay_license_mismatch",
+        });
+        return { fetched: 0, cached: true };
+    }
+    if (sigP.machineId !== machineId) {
+        process.stderr.write(`[community-sync] Tier B signature payload machine-id mismatch; cross-machine replay attempt. Rejecting.\n`);
+        safeAppend("community.sync_error", {
+            tier: "B",
+            reason: "replay_machine_mismatch",
+        });
+        return { fetched: 0, cached: true };
+    }
+    // expiresAt must be in the future, AND within a 24h freshness window so
+    // long-lived signed blobs can't be replayed weeks later. The server's
+    // signResponsePayload should set expiresAt = now + 24h; we enforce that
+    // ceiling here.
+    const now = Date.now();
+    const expiresAtMs = Date.parse(sigP.expiresAt);
+    if (!Number.isFinite(expiresAtMs) || expiresAtMs < now) {
+        process.stderr.write(`[community-sync] Tier B signature expired (${sigP.expiresAt}); discarding fetched rules.\n`);
+        safeAppend("community.sync_error", {
+            tier: "B",
+            reason: "signature_expired",
+        });
+        return { fetched: 0, cached: true };
+    }
+    if (expiresAtMs - now > 36 * 60 * 60 * 1000) {
+        // > 36h ahead = server is over-issuing or the response is a replay
+        // from a past server config. Reject — keeps the replay window small.
+        process.stderr.write(`[community-sync] Tier B signature expires too far in the future (${sigP.expiresAt}); rejecting.\n`);
+        safeAppend("community.sync_error", {
+            tier: "B",
+            reason: "signature_freshness_violation",
+        });
+        return { fetched: 0, cached: true };
+    }
+    const fresh = normalizeIncoming("tier-B-pro", parsed.rules);
+    const merged = mergeRules(store, "tier-B-pro", fresh);
+    const etag = readEtag(res.headers);
+    if (etag)
+        merged.source_tier_b_etag = etag;
+    saveCommunityStore(merged);
+    safeAppend("community.sync_ok", { tier: "B", fetched: fresh.length });
+    return { fetched: fresh.length, cached: false };
+}
+/**
+ * Resolve a license token from the activation store. Returns null if the
+ * user has no license loaded (free user). We deliberately avoid throwing
+ * here so the caller can skip Tier B gracefully.
+ */
+function resolveLicenseToken() {
+    try {
+        // Lazy import — keeps community-sync.ts importable in tests without
+        // dragging the full activation surface.
+        const licenseFile = join(homedir(), ".contextengine", "license.json");
+        if (!existsSync(licenseFile))
+            return null;
+        const data = JSON.parse(readFileSync(licenseFile, "utf-8"));
+        return typeof data.key === "string" && data.key.length > 0
+            ? data.key
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function syncAll(opts = {}) {
+    const tierA = await syncTierA(opts);
+    const token = resolveLicenseToken();
+    if (!token) {
+        process.stderr.write(`[community-sync] Tier B skipped: no license loaded (free tier). ` +
+            `Activate Pro to receive curated community rules: ` +
+            `https://api.compr.ch/contextengine/pricing\n`);
+        return { tierA, tierB: null };
+    }
+    const tierB = await syncTierB(token, opts);
+    return { tierA, tierB };
+}
+// ---------------------------------------------------------------------------
+// Chunk integration — feed the search pipeline
+// ---------------------------------------------------------------------------
+/**
+ * Convert the community store into Chunks shaped exactly like
+ * learningsToChunks() so search.ts can index them through the same
+ * BM25 / vector pipeline.
+ *
+ * Each chunk's `section` is prefixed with "[community:tier-A]" /
+ * "[community:tier-B]" so the UI can render a "(community)" badge by
+ * pattern-matching the section, and so duplicate detection against the
+ * local Learnings Store doesn't merge identical-looking content.
+ */
+export function communityRulesToChunks() {
+    const store = loadCommunityStore();
+    return store.rules.map((r) => {
+        const tierBadge = r.source === "tier-A-public" ? "tier-A" : "tier-B";
+        return {
+            source: `🌐 Community Rules (${tierBadge})`,
+            section: `[community:${tierBadge}] [${r.category}] ${r.rule}`,
+            content: [
+                `**Rule:** ${r.rule}`,
+                `**Category:** ${r.category}`,
+                `**Source:** community / ${r.source}`,
+                r.context ? `**Context:** ${r.context}` : "",
+                r.tags?.length ? `**Tags:** ${r.tags.join(", ")}` : "",
+                r.project_cluster ? `**Project cluster:** ${r.project_cluster}` : "",
+                `_Fetched: ${r.fetched_at.split("T")[0]}_`,
+            ]
+                .filter(Boolean)
+                .join("\n"),
+            lineStart: 0,
+            lineEnd: 0,
+            indexedAt: r.fetched_at,
+        };
+    });
+}
+/**
+ * Deduplicate a chunk list against the community chunks by SHA-256 of
+ * the rule content. The local Learnings Store wins (we drop the
+ * community chunk that matches). Use this where the engine combines
+ * local + community chunks into one search corpus.
+ */
+export function mergeWithDedup(localChunks, communityChunks) {
+    if (communityChunks.length === 0)
+        return localChunks;
+    const localHashes = new Set();
+    for (const c of localChunks) {
+        const ruleLine = extractRuleLine(c.content);
+        if (ruleLine)
+            localHashes.add(hashContent(ruleLine));
+    }
+    const filtered = [];
+    for (const c of communityChunks) {
+        const ruleLine = extractRuleLine(c.content);
+        if (ruleLine && localHashes.has(hashContent(ruleLine)))
+            continue;
+        filtered.push(c);
+    }
+    return [...localChunks, ...filtered];
+}
+function extractRuleLine(content) {
+    // Both learningsToChunks and communityRulesToChunks render "**Rule:** ..."
+    const m = content.match(/\*\*Rule:\*\*\s*(.+)/);
+    if (!m)
+        return null;
+    return m[1].trim().toLowerCase();
+}
+function hashContent(s) {
+    return createHash("sha256").update(s).digest("hex");
+}
+//# sourceMappingURL=community-sync.js.map

package/dist/hooks.d.ts

@@ -71,6 +71,70 @@ export declare function runDocCoverage(policy: Policy, files: StagedFile[], repo
 export declare function hashDocSection(filePath: string, anchor: string): string | null;
 export declare function formatSecretViolations(violations: SecretViolation[]): string;
 export declare function formatDocCoverageViolations(violations: DocCoverageViolation[]): string;
+/** Canonical bypass marker. Lives at the top of the checker so editors
+ *  can grep for it when reviewing the audit story. */
+export declare const COMMIT_BYPASS_PREFIX = "--skip-multi-agent-reason:";
+export interface CommitMessageViolation {
+    kind: "missing-pattern" | "bypass";
+    severity: "block" | "warn";
+    ruleId: string;
+    matchedFiles: string[];
+    pattern: string;
+    description?: string;
+    /** Only set when kind === "bypass". The free-text reason captured
+     *  after `--skip-multi-agent-reason:` for the audit log. */
+    bypassReason?: string;
+}
+/** Extract a bypass reason from the commit message. Returns the
+ *  reason text (trimmed) or null when absent.
+ *
+ *  Hardened 2026-06-26 (verifier Bypass #5 + #11):
+ *    - The bypass-marker MUST appear at the start of its own line
+ *      (only leading whitespace allowed). Mid-line or commented-out
+ *      markers like `# Note: do NOT use --skip-multi-agent-reason: ever`
+ *      are REJECTED — the `#` (or any non-whitespace char) before the
+ *      prefix on the same line disqualifies the line.
+ *    - Reason must be ≥ MIN_BYPASS_REASON_LENGTH chars (20).
+ *    - Reason must contain at least one whitespace character — real
+ *      reasons are prose ("emergency rollback at 03:00 UTC"), not
+ *      alphanumeric placeholders ("12345" / "abc123def456…"). A token
+ *      without spaces is almost certainly a defeat attempt.
+ */
+export declare function extractBypassReason(commitMessage: string): string | null;
+/**
+ * Strip any top-level alternation branch from a policy regex pattern
+ * that contains the literal COMMIT_BYPASS_PREFIX. Verifier Bypass #3:
+ * the canonical policy pattern
+ *
+ *   Multi-agent: wf_[a-z0-9-]+|--skip-multi-agent-reason: .+
+ *
+ * had two branches in one pattern; the second branch matched the literal
+ * bypass marker anywhere in the message (including mid-line, commented
+ * out, etc.), short-circuiting the strict line-anchored validation in
+ * extractBypassReason. Fix: the matcher in runCommitMessageRequired
+ * ignores the bypass-marker branch entirely — bypass MUST go through
+ * extractBypassReason's hardened validation.
+ *
+ * Returns the cleaned pattern. If every branch is bypass-related (rare
+ * footgun), returns null — caller treats as "no positive branch to
+ * satisfy", which is the safe default.
+ */
+export declare function stripBypassBranchFromPattern(pattern: string): string | null;
+/**
+ * Apply policy.commit_message_required rules to a staged-file list +
+ * commit message. Returns one entry per fired rule (either a
+ * missing-pattern violation OR a bypass acknowledgement).
+ *
+ * Empty list = nothing fired (either no rule's `paths` matched, or every
+ * fired rule was satisfied by the message).
+ *
+ * IMPORTANT: This does NOT itself decide exit codes. The caller (CLI)
+ * decides: missing-pattern + severity=block → exit 1 + hook.block event;
+ * bypass → exit 0 + policy.skipped event with the reason.
+ */
+export declare function runCommitMessageRequired(policy: Policy, files: StagedFile[], commitMessage: string): CommitMessageViolation[];
+export declare function formatCommitMessageViolations(violations: CommitMessageViolation[]): string;
+export declare function formatCommitMessageViolationsJson(violations: CommitMessageViolation[]): string;
 export declare function formatSecretViolationsJson(violations: SecretViolation[]): string;
 export declare function formatDocCoverageViolationsJson(violations: DocCoverageViolation[]): string;
 //# sourceMappingURL=hooks.d.ts.map