// enrich.hpp - Safe, opt-in enrichment of an AdvantageStore from remote // knowledge sources, via the secure transport layer. // // SAFETY POSTURE (all gates default-closed): // * Enrichment is OFF unless a policy is explicitly passed. // * Only schemes in the allowlist are permitted; the default allowlist is // { "https" } -- no plaintext http, no ssh/sftp, and no file:// (which // reads LOCAL files and is not covered by the host allowlist) unless the // caller opts in explicitly. // * Only hosts in `allowedHosts` are permitted; the default is EMPTY, which // allows nothing. A caller must name every host it trusts. // * TLS certificate + hostname verification stays ON (inherited from the // transport layer's secure defaults). // * Each fetch is bounded by a byte cap and a maximum number of knowledge // lines; oversized responses are rejected. // * Fetched text is SANITIZED (control chars stripped, length-capped) and // stored in SourceAdvantage::remoteKnowledge -- kept separate from // authored knowledge so untrusted remote data can never masquerade as // authored content. // * All downloads go through the content-addressed store, so enrichment is // idempotent and integrity-checked (optional sha256 pin per source). // // Nothing here can reach the network unless the caller both links transport // and passes a policy that names the schemes and hosts it trusts. #ifndef ADVANTAGE_ENRICH_HPP #define ADVANTAGE_ENRICH_HPP #include #include #include #include "advantage_store.hpp" namespace advantage { struct EnrichPolicy { // Must be true or enrichment is a no-op. Forces the caller to opt in. bool enabled = false; // Directory for the content-addressed download store. std::string storeDir = "./advantage-store"; // Permitted URL schemes. Default: https only. Add "file" deliberately. std::vector allowedSchemes = {"https"}; // Permitted hosts (exact match, case-insensitive). EMPTY => deny all // network hosts. file:// has no host and is governed by allowedSchemes. std::vector allowedHosts; // Per-source download cap and sanitization limits. std::size_t maxBytesPerSource = 1u * 1024u * 1024u; // 1 MiB std::size_t maxLinesPerSource = 1000; std::size_t maxLineLength = 2000; // If true, a single source failing aborts the whole enrichment with an // error. If false (default), failures are collected per-source and // enrichment continues -- a safer, more resilient default. bool failFast = false; }; struct EnrichReport { std::size_t sourcesConsidered = 0; // sourceAdvantages with a URL std::size_t fetchesAttempted = 0; std::size_t fetchesSucceeded = 0; std::size_t fetchesFromCache = 0; std::size_t linesAdded = 0; std::vector warnings; // per-source skips/failures bool ok = true; // false only if failFast tripped }; // Enrich `store` in place by fetching declared knowledgeSources that pass the // policy gates. Returns a report; `store` is mutated only with sanitized, // clearly-attributed remote knowledge. Safe to call repeatedly (idempotent). EnrichReport enrich(AdvantageStore& store, const EnrichPolicy& policy); } // namespace advantage #endif // ADVANTAGE_ENRICH_HPP