@danielblomma/cortex-mcp 2.4.0 → 2.4.1

package/scaffold/mcp/dist/core/enterprise-host-identity.js

@@ -0,0 +1,193 @@
+import { chownSync, chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const HOST_IDENTITY_FILENAME = "enterprise-host-identity.json";
+const HOST_IDENTITY_VERSION = 2;
+function configuredHomeDir(homeDir) {
+    return homeDir ?? process.env.HOME?.trim() ?? homedir();
+}
+function hostIdentityDir(options = {}, create = false) {
+    try {
+        const home = realpathSync(configuredHomeDir(options.homeDir));
+        const dir = join(home, ".cortex");
+        if (existsSync(dir)) {
+            const stat = lstatSync(dir);
+            if (!stat.isDirectory() || stat.isSymbolicLink())
+                return null;
+            if (realpathSync(dir) !== dir)
+                return null;
+            if (options.owner) {
+                if (stat.uid !== options.owner.uid && stat.uid !== 0)
+                    return null;
+                chownSync(dir, options.owner.uid, options.owner.gid);
+                chmodSync(dir, 0o700);
+            }
+            return dir;
+        }
+        if (!create)
+            return null;
+        mkdirSync(dir, { mode: 0o700 });
+        if (options.owner) {
+            chownSync(dir, options.owner.uid, options.owner.gid);
+        }
+        chmodSync(dir, 0o700);
+        return dir;
+    }
+    catch {
+        return null;
+    }
+}
+function hostIdentityPath(options = {}, createDir = false) {
+    const dir = hostIdentityDir(options, createDir);
+    return dir ? join(dir, HOST_IDENTITY_FILENAME) : null;
+}
+function readHostIdentity(options = {}) {
+    const path = hostIdentityPath(options);
+    if (!path)
+        return null;
+    if (!existsSync(path))
+        return null;
+    try {
+        const stat = lstatSync(path);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            return null;
+        if (options.owner &&
+            stat.uid !== options.owner.uid &&
+            stat.uid !== 0) {
+            return null;
+        }
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (parsed.version !== HOST_IDENTITY_VERSION ||
+            typeof parsed.credential_id !== "string" ||
+            !/^[a-f0-9]{64}$/.test(parsed.credential_id) ||
+            typeof parsed.endpoint_sha256 !== "string" ||
+            !/^[a-f0-9]{64}$/.test(parsed.endpoint_sha256)) {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Atomically bind user-global Enterprise services and artifacts to one
+ * endpoint/API-key identity. Malformed existing enrollment fails closed.
+ */
+export function claimEnterpriseHostIdentity(credentialId, endpoint, options = {}) {
+    if (!/^[a-f0-9]{64}$/.test(credentialId))
+        return false;
+    const endpointSha256 = createHash("sha256")
+        .update(endpoint.trim().replace(/\/+$/, ""), "utf8")
+        .digest("hex");
+    const path = hostIdentityPath(options, true);
+    if (!path)
+        return false;
+    if (existsSync(path)) {
+        const existing = readHostIdentity(options);
+        if (!existing || existing.endpoint_sha256 !== endpointSha256) {
+            return false;
+        }
+        if (existing.credential_id === credentialId) {
+            try {
+                if (options.owner) {
+                    chownSync(path, options.owner.uid, options.owner.gid);
+                }
+                chmodSync(path, 0o600);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }
+        return replaceHostIdentity(path, {
+            version: HOST_IDENTITY_VERSION,
+            credential_id: credentialId,
+            endpoint_sha256: endpointSha256,
+        }, options.owner);
+    }
+    try {
+        writeFileSync(path, JSON.stringify({
+            version: HOST_IDENTITY_VERSION,
+            credential_id: credentialId,
+            endpoint_sha256: endpointSha256,
+        }, null, 2) + "\n", { encoding: "utf8", mode: 0o600, flag: "wx" });
+        if (options.owner) {
+            chownSync(path, options.owner.uid, options.owner.gid);
+        }
+        chmodSync(path, 0o600);
+        return true;
+    }
+    catch {
+        // Another process may have won the create race. Only the same identity
+        // is accepted after re-reading the completed enrollment record.
+        const existing = readHostIdentity(options);
+        return (existing?.credential_id === credentialId &&
+            existing.endpoint_sha256 === endpointSha256);
+    }
+}
+function replaceHostIdentity(path, identity, owner) {
+    const temporaryPath = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        writeFileSync(temporaryPath, JSON.stringify(identity, null, 2) + "\n", { encoding: "utf8", mode: 0o600, flag: "wx" });
+        if (owner) {
+            chownSync(temporaryPath, owner.uid, owner.gid);
+        }
+        chmodSync(temporaryPath, 0o600);
+        renameSync(temporaryPath, path);
+        chmodSync(path, 0o600);
+        return true;
+    }
+    catch {
+        try {
+            unlinkSync(temporaryPath);
+        }
+        catch {
+            // Best effort.
+        }
+        return false;
+    }
+}
+export function matchesEnterpriseHostIdentity(credentialId, options = {}) {
+    if (!/^[a-f0-9]{64}$/.test(credentialId))
+        return false;
+    return readHostIdentity(options)?.credential_id === credentialId;
+}
+export function inspectEnterpriseHostIdentity(credentialId, endpoint, options = {}) {
+    if (!/^[a-f0-9]{64}$/.test(credentialId))
+        return "invalid";
+    let home;
+    try {
+        home = realpathSync(configuredHomeDir(options.homeDir));
+    }
+    catch {
+        return "invalid";
+    }
+    const dir = join(home, ".cortex");
+    if (!existsSync(dir))
+        return "unbound";
+    try {
+        const dirStat = lstatSync(dir);
+        if (!dirStat.isDirectory() ||
+            dirStat.isSymbolicLink() ||
+            realpathSync(dir) !== dir) {
+            return "invalid";
+        }
+    }
+    catch {
+        return "invalid";
+    }
+    const path = join(dir, HOST_IDENTITY_FILENAME);
+    if (!existsSync(path))
+        return "unbound";
+    const existing = readHostIdentity(options);
+    if (!existing)
+        return "invalid";
+    const endpointSha256 = createHash("sha256")
+        .update(endpoint.trim().replace(/\/+$/, ""), "utf8")
+        .digest("hex");
+    if (existing.endpoint_sha256 !== endpointSha256)
+        return "conflict";
+    return existing.credential_id === credentialId ? "match" : "rotation";
+}

package/scaffold/mcp/dist/core/enterprise-identity.js

@@ -0,0 +1,18 @@
+import { join } from "node:path";
+import { loadEnterpriseConfig } from "./config.js";
+import { enterpriseCredentialId } from "./license.js";
+/**
+ * Resolve the opaque per-user Enterprise identity for a project.
+ *
+ * The identifier binds the normalized endpoint and API key without
+ * persisting either credential in shared daemon metadata.
+ */
+export function configuredEnterpriseCredentialId(cwd) {
+    const config = loadEnterpriseConfig(join(cwd, ".context"));
+    const apiKey = config.enterprise.api_key.trim();
+    const endpoint = (config.enterprise.base_url ||
+        config.enterprise.endpoint).trim();
+    if (!apiKey || !endpoint)
+        return null;
+    return enterpriseCredentialId(endpoint, apiKey);
+}

package/scaffold/mcp/dist/core/enterprise-rotation.js

@@ -0,0 +1,158 @@
+import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync, rmdirSync, unlinkSync, } from "node:fs";
+import { join, resolve } from "node:path";
+import { homedir } from "node:os";
+const SKILL_NAME_RE = /^[a-z0-9](?:[a-z0-9-]{0,78}[a-z0-9])?$/;
+const OWNERSHIP_FILENAME = ".cortex-managed.json";
+const STATE_FILES = [
+    "skills.local.json",
+    "workflows.local.json",
+    "capabilities.local.json",
+    ".skills-update-applied.json",
+];
+function configuredHome(homeDir) {
+    return homeDir ?? process.env.HOME?.trim() ?? homedir();
+}
+function safeDirectory(path) {
+    if (!existsSync(path))
+        return null;
+    const stat = lstatSync(path);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        throw new Error(`${path} is not a safe directory`);
+    }
+    const real = realpathSync(path);
+    if (real !== path)
+        throw new Error(`${path} is not a canonical directory`);
+    return real;
+}
+function inspectManagedSkill(root, cli, name) {
+    if (!SKILL_NAME_RE.test(name)) {
+        throw new Error("invalid managed skill name");
+    }
+    const dir = resolve(root, name);
+    if (!dir.startsWith(`${root}/`)) {
+        throw new Error("managed skill escapes its root");
+    }
+    const stat = lstatSync(dir);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        throw new Error("managed skill target is not a safe directory");
+    }
+    if (realpathSync(dir) !== dir) {
+        throw new Error("managed skill target is not canonical");
+    }
+    const marker = join(dir, OWNERSHIP_FILENAME);
+    if (!existsSync(marker))
+        return null;
+    const markerStat = lstatSync(marker);
+    if (!markerStat.isFile() || markerStat.isSymbolicLink()) {
+        throw new Error("managed skill ownership marker is unsafe");
+    }
+    const parsed = JSON.parse(readFileSync(marker, "utf8"));
+    if (parsed.version !== 1 ||
+        parsed.manager !== "cortex" ||
+        parsed.cli !== cli ||
+        parsed.name !== name) {
+        throw new Error("managed skill ownership marker is invalid");
+    }
+    const entries = readdirSync(dir);
+    const unexpected = entries.filter((entry) => entry !== OWNERSHIP_FILENAME && entry !== "SKILL.md");
+    if (unexpected.length > 0) {
+        throw new Error("managed skill directory contains unowned files");
+    }
+    const skill = join(dir, "SKILL.md");
+    if (existsSync(skill)) {
+        const skillStat = lstatSync(skill);
+        if (!skillStat.isFile() || skillStat.isSymbolicLink()) {
+            throw new Error("managed skill file is unsafe");
+        }
+    }
+    return { dir, marker, skill: existsSync(skill) ? skill : null };
+}
+function recordedSkills(home) {
+    const statePath = join(home, ".cortex", "skills.local.json");
+    if (!existsSync(statePath))
+        return [];
+    const stat = lstatSync(statePath);
+    if (!stat.isFile() || stat.isSymbolicLink()) {
+        throw new Error("skills state is unsafe");
+    }
+    const parsed = JSON.parse(readFileSync(statePath, "utf8"));
+    if (!parsed.skills || typeof parsed.skills !== "object")
+        return [];
+    const records = [];
+    for (const [key, value] of Object.entries(parsed.skills)) {
+        const [keyCli, name] = key.includes(":")
+            ? key.split(":", 2)
+            : [String(value?.cli ?? ""), key];
+        if ((keyCli !== "claude" && keyCli !== "codex") ||
+            !SKILL_NAME_RE.test(name)) {
+            throw new Error("skills state contains an unsafe record");
+        }
+        records.push({ cli: keyCli, name });
+    }
+    return records;
+}
+/**
+ * Purge credential-specific artifacts before an explicit API-key rotation.
+ * Every path is derived from the target user's home and every skill deletion
+ * requires the Cortex ownership marker. Any ambiguity aborts rotation.
+ */
+export function prepareEnterpriseCredentialRotation(homeDir) {
+    try {
+        const home = realpathSync(configuredHome(homeDir));
+        const cortexDir = safeDirectory(join(home, ".cortex"));
+        if (!cortexDir)
+            return true;
+        const targets = new Map();
+        const recorded = recordedSkills(home);
+        for (const cli of ["claude", "codex"]) {
+            const cliDir = safeDirectory(join(home, cli === "codex" ? ".codex" : ".claude"));
+            if (!cliDir) {
+                if (recorded.some((record) => record.cli === cli))
+                    return false;
+                continue;
+            }
+            const root = safeDirectory(join(cliDir, "skills"));
+            if (!root) {
+                if (recorded.some((record) => record.cli === cli))
+                    return false;
+                continue;
+            }
+            for (const name of readdirSync(root)) {
+                const candidate = join(root, name);
+                const stat = lstatSync(candidate);
+                if (!stat.isDirectory() || stat.isSymbolicLink())
+                    continue;
+                const target = inspectManagedSkill(root, cli, name);
+                if (target)
+                    targets.set(target.dir, target);
+            }
+            for (const record of recorded.filter((entry) => entry.cli === cli)) {
+                const candidate = join(root, record.name);
+                if (!existsSync(candidate))
+                    continue;
+                const target = inspectManagedSkill(root, cli, record.name);
+                if (!target) {
+                    // Legacy state without an ownership marker is not deletion
+                    // authority. Abort and require the operator to resolve it.
+                    return false;
+                }
+                targets.set(target.dir, target);
+            }
+        }
+        for (const target of targets.values()) {
+            if (target.skill)
+                unlinkSync(target.skill);
+            unlinkSync(target.marker);
+            rmdirSync(target.dir);
+        }
+        for (const filename of STATE_FILES) {
+            const path = join(cortexDir, filename);
+            if (existsSync(path))
+                unlinkSync(path);
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/scaffold/mcp/dist/core/govern-paths.js

@@ -0,0 +1,21 @@
+const MANAGED_PATHS = {
+    claude: {
+        darwin: "/Library/Application Support/ClaudeCode/managed-settings.json",
+        linux: "/etc/claude-code/managed-settings.json",
+    },
+    codex: {
+        darwin: "/Library/Application Support/Codex/requirements.toml",
+        linux: "/etc/codex/requirements.toml",
+    },
+    copilot: {
+        darwin: "/usr/local/bin/copilot",
+        linux: "/usr/local/bin/copilot",
+    },
+};
+export function getGovernManagedPath(cli, os) {
+    const path = MANAGED_PATHS[cli][os];
+    if (!path) {
+        throw new Error(`govern install for ${cli} not yet supported on ${os}`);
+    }
+    return path;
+}

package/scaffold/mcp/dist/core/index.js

@@ -0,0 +1,14 @@
+// Config
+export { loadEnterpriseConfig, resolveEnterpriseActivation } from "./config.js";
+// Telemetry
+export { TelemetryCollector } from "./telemetry/collector.js";
+// Audit
+export { AuditWriter } from "./audit/writer.js";
+export { queryAuditLog } from "./audit/query.js";
+// RBAC
+export { checkAccess, getAccessDeniedMessage } from "./rbac/check.js";
+// Policy
+export { PolicyStore } from "./policy/store.js";
+// Prompt injection
+export { scanForInjection, sanitizeContent } from "./policy/injection.js";
+export { enforceInjectionPolicy, isInjectionDefenseActive, buildViolationPayload } from "./policy/enforce.js";

package/scaffold/mcp/dist/core/license.js

@@ -0,0 +1,278 @@
+import { createHash, randomUUID } from "node:crypto";
+import { chmodSync, readFileSync, writeFileSync, mkdirSync, existsSync, renameSync, unlinkSync, } from "node:fs";
+import { resolveTelemetryStateDir, telemetryStatePath } from "./telemetry/state-dir.js";
+import { isAllowedEnterpriseEndpoint } from "./secure-endpoint.js";
+export { isAllowedEnterpriseEndpoint as isAllowedLicenseEndpoint };
+const CACHE_FILE = "license_cache.json";
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24h fresh
+const GRACE_PERIOD_MS = 7 * 24 * 60 * 60 * 1000; // 7d grace if endpoint unreachable
+const REQUEST_TIMEOUT_MS = 5000;
+function cachePath(contextDir) {
+    return telemetryStatePath(contextDir, CACHE_FILE);
+}
+function isIsoTimestamp(value) {
+    if (typeof value !== "string")
+        return false;
+    const timestamp = new Date(value).getTime();
+    return Number.isFinite(timestamp) && new Date(timestamp).toISOString() === value;
+}
+function readCache(contextDir) {
+    const path = cachePath(contextDir);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, "utf8");
+        const parsed = JSON.parse(raw);
+        if (!parsed ||
+            typeof parsed !== "object" ||
+            parsed.version !== 2 ||
+            typeof parsed.endpoint !== "string" ||
+            !parsed.endpoint ||
+            typeof parsed.api_key_sha256 !== "string" ||
+            !/^[a-f0-9]{64}$/.test(parsed.api_key_sha256) ||
+            !parsed.result ||
+            typeof parsed.result !== "object" ||
+            typeof parsed.result.valid !== "boolean" ||
+            !isIsoTimestamp(parsed.cached_at)) {
+            deleteCache(contextDir);
+            return null;
+        }
+        if (parsed.result.valid) {
+            if (typeof parsed.result.edition !== "string" ||
+                !Array.isArray(parsed.result.features) ||
+                !parsed.result.features.every((feature) => typeof feature === "string") ||
+                !isIsoTimestamp(parsed.result.expires_at) ||
+                typeof parsed.result.max_repos !== "number" ||
+                !Number.isFinite(parsed.result.max_repos) ||
+                parsed.result.max_repos < 0 ||
+                !isIsoTimestamp(parsed.result.verified_at) ||
+                !["remote", "cache"].includes(parsed.result.source)) {
+                deleteCache(contextDir);
+                return null;
+            }
+        }
+        else if (typeof parsed.result.reason !== "string" ||
+            !isIsoTimestamp(parsed.result.verified_at) ||
+            !["remote", "cache", "grace_expired"].includes(parsed.result.source)) {
+            deleteCache(contextDir);
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        deleteCache(contextDir);
+        return null;
+    }
+}
+function writeCache(contextDir, entry) {
+    const path = cachePath(contextDir);
+    const temporaryPath = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        mkdirSync(resolveTelemetryStateDir(contextDir), { recursive: true });
+        writeFileSync(temporaryPath, JSON.stringify(entry, null, 2) + "\n", { encoding: "utf8", mode: 0o600, flag: "wx" });
+        chmodSync(temporaryPath, 0o600);
+        renameSync(temporaryPath, path);
+        chmodSync(path, 0o600);
+    }
+    catch {
+        try {
+            unlinkSync(temporaryPath);
+        }
+        catch {
+            // Best effort.
+        }
+        // Cache failures are non-fatal — license check just won't be cached.
+    }
+}
+function deleteCache(contextDir) {
+    const path = cachePath(contextDir);
+    if (!existsSync(path))
+        return;
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        // ignore — best-effort
+    }
+}
+function ageMs(isoTimestamp) {
+    return Date.now() - new Date(isoTimestamp).getTime();
+}
+export function normalizeLicenseEndpoint(endpoint) {
+    return endpoint.trim().replace(/\/+$/, "");
+}
+function apiKeyFingerprint(apiKey) {
+    return createHash("sha256").update(apiKey, "utf8").digest("hex");
+}
+function cacheMatchesCredential(cached, endpoint, apiKey) {
+    return (cached.version === 2 &&
+        cached.endpoint === normalizeLicenseEndpoint(endpoint) &&
+        cached.api_key_sha256 === apiKeyFingerprint(apiKey));
+}
+export function enterpriseCredentialId(endpoint, apiKey) {
+    return createHash("sha256")
+        .update(normalizeLicenseEndpoint(endpoint), "utf8")
+        .update("\0", "utf8")
+        .update(apiKey, "utf8")
+        .digest("hex");
+}
+function cacheResultIsUnexpired(cached) {
+    if (!cached.result.valid)
+        return false;
+    const expiresAt = new Date(cached.result.expires_at).getTime();
+    return Number.isFinite(expiresAt) && expiresAt > Date.now();
+}
+function cacheAgeIsWithin(cached, limitMs) {
+    const age = ageMs(cached.cached_at);
+    return Number.isFinite(age) && age >= 0 && age < limitMs;
+}
+async function fetchLicense(endpoint, apiKey, instanceId, clientVersion) {
+    const url = `${endpoint.replace(/\/$/, "")}/api/v1/license/verify`;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+    try {
+        const res = await fetch(url, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify({
+                instance_id: instanceId,
+                client_version: clientVersion,
+            }),
+            signal: controller.signal,
+        });
+        if (res.status === 401 || res.status === 403) {
+            return {
+                valid: false,
+                reason: "authentication_rejected",
+                verified_at: new Date().toISOString(),
+                source: "remote",
+            };
+        }
+        if (!res.ok) {
+            // Rate limiting, server failures, and other transport-level responses
+            // may use an identity-matched positive cache during the grace period.
+            return null;
+        }
+        const json = (await res.json());
+        const verifiedAt = new Date().toISOString();
+        if (json.valid === true &&
+            typeof json.edition === "string" &&
+            Array.isArray(json.features) &&
+            json.features.every((feature) => typeof feature === "string") &&
+            isIsoTimestamp(json.expires_at) &&
+            new Date(json.expires_at).getTime() > Date.now() &&
+            typeof json.max_repos === "number" &&
+            Number.isFinite(json.max_repos) &&
+            json.max_repos >= 0) {
+            return {
+                valid: true,
+                edition: json.edition,
+                features: json.features,
+                expires_at: json.expires_at,
+                max_repos: json.max_repos,
+                verified_at: verifiedAt,
+                source: "remote",
+            };
+        }
+        return {
+            valid: false,
+            reason: json.valid === true
+                ? "malformed_license_response"
+                : String(json.reason ?? "unknown"),
+            verified_at: verifiedAt,
+            source: "remote",
+        };
+    }
+    catch {
+        // Network error, timeout, JSON parse error — treat as transient.
+        return null;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+/**
+ * Verify the license for the given api_key. Layered fallback:
+ *   1. If a positive cache (valid:true) is fresh (<24h), unexpired, and
+ *      bound to this endpoint + API-key fingerprint → use cache
+ *      Negative cache entries are never trusted; if one is encountered
+ *      it's deleted on the spot so a since-fixed remote can heal.
+ *   2. Otherwise try remote endpoint
+ *      - On valid:true → write positive cache, return result
+ *      - On valid:false (authoritative fail) → DELETE any positive
+ *        cache (so a revoked/expired key doesn't keep masquerading as
+ *        valid past its remote-side fail), return result, do NOT
+ *        cache the negative.
+ *      - On transient failure → fall back to the same identity-bound positive
+ *        cache if within the grace period (7d). Authentication rejection is
+ *        authoritative and never uses grace.
+ *   3. If no usable cache and endpoint unreachable → return invalid
+ *      (grace_expired).
+ *
+ * The caller decides what to do based on the result. Typically:
+ *   - valid:true  → activate enterprise hooks
+ *   - valid:false → community mode (no enterprise)
+ */
+export async function verifyLicense(contextDir, endpoint, apiKey, options = {}) {
+    if (!isAllowedEnterpriseEndpoint(endpoint)) {
+        deleteCache(contextDir);
+        return {
+            valid: false,
+            reason: "insecure_or_invalid_endpoint",
+            verified_at: new Date().toISOString(),
+            source: "remote",
+        };
+    }
+    let cached = readCache(contextDir);
+    // Defensive: a previous version of this code wrote negative results
+    // into the cache. Refuse to honour them and clean them up so a
+    // since-deployed fix on the remote can be observed.
+    if (cached && cached.result.valid === false) {
+        deleteCache(contextDir);
+        cached = null;
+    }
+    const matchingCache = cached && cacheMatchesCredential(cached, endpoint, apiKey)
+        ? cached
+        : null;
+    // Fresh positive cache: skip remote.
+    if (matchingCache &&
+        matchingCache.result.valid === true &&
+        cacheResultIsUnexpired(matchingCache) &&
+        cacheAgeIsWithin(matchingCache, CACHE_TTL_MS)) {
+        return { ...matchingCache.result, source: "cache" };
+    }
+    const remote = await fetchLicense(endpoint, apiKey, options.instance_id, options.client_version);
+    if (remote) {
+        if (remote.valid) {
+            writeCache(contextDir, {
+                version: 2,
+                endpoint: normalizeLicenseEndpoint(endpoint),
+                api_key_sha256: apiKeyFingerprint(apiKey),
+                result: remote,
+                cached_at: new Date().toISOString(),
+            });
+        }
+        else {
+            // Authoritative fail from remote — drop any stale positive cache
+            // so we don't bounce back to "valid" on the next call.
+            deleteCache(contextDir);
+        }
+        return remote;
+    }
+    // Remote unreachable. Fall back to positive cache if within grace.
+    if (matchingCache &&
+        matchingCache.result.valid === true &&
+        cacheResultIsUnexpired(matchingCache) &&
+        cacheAgeIsWithin(matchingCache, GRACE_PERIOD_MS)) {
+        return { ...matchingCache.result, source: "cache" };
+    }
+    return {
+        valid: false,
+        reason: "endpoint_unreachable_grace_expired",
+        verified_at: new Date().toISOString(),
+        source: "grace_expired",
+    };
+}