Home /Modules/advantage/enrich.hpp

enrich.hpp

advantage/enrich.hpp · 79 line(s) · c

// 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 <cstddef>
#include <string>
#include <vector>

#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<std::string> allowedSchemes = {"https"};

    // Permitted hosts (exact match, case-insensitive). EMPTY => deny all
    // network hosts. file:// has no host and is governed by allowedSchemes.
    std::vector<std::string> 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<std::string> 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