linkedin-studio/docs/ingestion-guard/plan.md

Ingestion-guard integration plan — when & where to wire llm-ingestion-guard

Status: planned (2026-07-16). Plan only — nothing wired yet, per the adoption brief's "don't implement now" instruction. This document is the repo's durable answer to when and where a write-time ingestion guard earns its place at our persist gates.

Guard: llm-ingestion-guard v0.2 (alpha, public API may change). Write-time sibling of query-time chatbot guardrails; hardens untrusted content flowing through an LLM step into a persisted, downstream-read store. Python, stdlib-only core, 3.10+.

Adoption brief (authoritative, self-contained): https://git.fromaitochitta.com/open/llm-ingestion-pipeline-security/raw/branch/main/docs/ADOPTION-BRIEF.md (§7 planning checklist, §3 the 8-step contract, §4 the OKF adapter, §8 honest limitations).

Grounded against 882f6ee by two independent read-only surveys (ingest surface + persist seams), 2026-07-16. Every seam below carries a file:line anchor.

1. Decision

Status = planned. The plugin has live untrusted-ingest paths (a react-to-URL command, an auto-fetching trend agent, an external-research newsletter fan-out), and it persists their output into stores a downstream agent later reads as trusted context. That satisfies the brief's §7 decisive condition. Nothing is wired. The guard is registered here as a dependency to add before the first automated external-origin ingest path goes fully live — and one such path (trends → session re-injection, §5.1) is arguably already live, so it is the first integration candidate, not a distant one.

We do not implement now. The brief is explicit ("kun planlegg og oppdater planene"), and wiring is gated on an unresolved interop decision (§7).

2. What the guard is (and is not) for us

It is not a query-time guardrail between the user and the model. It is a write gate: the last place the provenance of a piece of content is still known before it is committed to a store that a later agent reads as trusted. For this plugin that store is the second-brain (brain/profile.md, ingest/published/), the trends store, the specifics-bank, the post queue, and the state file's ## Recent Posts — all of which are re-surfaced into future model context. A poisoned concept committed at write time is read back later with its origin forgotten; the write gate is the only place to catch it.

3. Ingest-surface analysis (untrusted vs first-party)

Scored against the brief's §7 checklist. "Downstream trusted reader" = a command/agent/hook that later reads the store as context, which is what turns a write into a poisoning surface.

#	Path	Origin	Untrusted?	Persist target	Downstream trusted reader	Live?
1	trend-spotter agent (agents/trend-spotter.md) → trends CLI capture (scripts/trends/src/cli.ts:294)	Auto-fetched web/vendor/regulator content (WebSearch/WebFetch + research MCPs)	YES — external	trends/trends.json — source/title/url/summary stored verbatim (scripts/trends/src/item.ts:24-48)	session-start.mjs:38-78 auto-reinjects into the next session's context — no human in the loop	LIVE
2	brain ingest / scanInbox (scripts/brain/src/ingest.ts:172-192,:247)	User's own published posts, dropped into ingest/inbox/ (manual)	Origin first-party today; untrusted-capable (drop-zone accepts any file; SB-S4 connector would automate it)	ingest/published/<id>.md	voice-trainer gold source (agents/voice-trainer.md:136,144); brain consolidate → brain/profile.md; assemble/reconcile	LIVE (manual)
3	/linkedin:newsletter research fan-out (commands/newsletter.md:461-475)	Open-web research agents (WebSearch/WebFetch)	YES — external	specifics-bank ekstern bindings (scripts/specifics-bank/src/kilder.ts:51-52) + NN-kilder.md + queue.json	Edition prose + sources ledger; queue readers	LIVE
4	/linkedin:react, :post, :pipeline, :batch URL ingest (commands/react.md:52, post.md:62, pipeline.md:13, batch.md:12)	External URL (news, blog, YouTube, social threads) via WebFetch	YES — external	react/post: clipboard + state ## Recent Posts metadata only (raw content not persisted); pipeline/batch: draft files + queue.json	state ## Recent Posts re-injected (user-prompt-context.mjs:109-117, session-start.mjs:341); queue readers	LIVE
5	/linkedin:import CSV (scripts/analytics/src/parsers/csv-parser.ts)	User's own LinkedIn analytics CSV export	First-party origin; container-layer parse surface	analytics/posts/*.json (storage.ts:143-160)	report/audit/analyze, analytics-interpreter, brain assemble	LIVE
6	/linkedin:competitive, :outreach (commands/competitive.md:33, outreach.md:223)	WebSearch of competitor/partner/event content	YES — external	Nothing durable (inline report only)	— (no persist)	LIVE
7	Received third-party OKF bundle	External bundle	YES — external	does not exist	—	FUTURE / not built
8	setup, onboarding, first-post, quick, specifics-bank, voice-samples	User's own typed/pasted content	No — first-party	state file / voice-samples / specifics-bank	content commands	LIVE

4. Where the guard applies — and where it deliberately does not

Applies (wire here): the untrusted boundaries — rows 1–5. Trust follows the data's origin, not the insertion channel (brief §7): a manual paste of an external article (/linkedin:react) is still external.

Does not apply (out of scope by design):

• First-party authoring (row 8): onboarding, setup, typed post ideas, specifics-bank (human-only), voice-samples, the user's own profile edits. The guard's threat model does not target trusted-author in-place edits.
• Fetch-but-no-persist (row 6): competitive/outreach fetch external content but write nothing durable — there is no downstream-trusted store to poison, so the write-time guard has no seam. (Their risk is query-time, a different tool's job.)
• Row 2 today is first-party by origin (the user's own posts). It becomes an untrusted boundary the moment SB-S4 (the EU/EEA DMA connector) or any received-bundle path automates the inbox — see §9.

5. Integration points (persist gates) + minimal wiring

Key structural finding: every external fetch in this plugin goes through the model's WebFetch/WebSearch/ MCP tools — there is no raw-HTTP your_model() seam in plugin code. The fetch → transform → persist pipeline is: model tool call → agent reasoning → deterministic CLI write. So the guard's classic two-bookend model (prepare_input → your_model → screen_output) only half-maps: screen_output (scan-before-persist) wires in cleanly at the deterministic CLI write points; prepare_input (sanitize+fence before the model) has no clean code seam because the fetch and transform happen inside the model's turn (§6).

Coverage gap to know: hooks/scripts/content-gatekeeper.mjs is the only PreToolUse(Write|Edit) choke-point, but it inspects the file path, never the content bytes, and only fires for the Write/Edit tool on drafts/assets paths. The four durable trusted-context stores below are all written via Bash-invoked node/tsx, so they bypass the gate entirely. A byte-level guard must wire at the CLI write points, not solely at content-gatekeeper.

Ranked by automated-reinjection risk (highest first):

5.1 trends capture — the one live automated poison→reinject loop (priority 1)

• Seam: before store.ts persists to trends/trends.json, in scripts/trends/src/cli.ts capture.
• Wiring: screen_output(item.title + "\n" + item.summary, PRESET_USER_UPLOAD); on Disposition.FAIL_SECURE, route the item into the CLI's existing errors[] channel (cli.ts:294-320) instead of persisting — a drop, not a crash.
• Why first: external content, stored verbatim, auto-surfaced back into future model context by session-start.mjs with no human gate. This is the sharpest write→trusted-read loop in the plugin.

5.2 brain ingest / scanInbox — the voice/profile gold seam (priority 2)

• Seam: writePublished(rec) in scripts/brain/src/ingest.ts:172-192; especially the scanInbox (:247) path that reads user-dropped ingest/inbox/*.md.
• Wiring: screen_output(body, ...) before write; FAIL_SECURE → do not promote to ingest/published/, log to a rejects sidecar. Once a bundle-shaped receive lands, switch to okf.import_bundle (§8).
• Why: ingest/published/ is the ranked-#1 gold source for voice-trainer and feeds profile.md via consolidation — the highest-trust downstream read in the plugin. Note the existing provenance=published guard here is an anti-model-collapse control (authorship axis), not an anti-injection control (origin axis) — the two are orthogonal; this seam has the former, not the latter.

5.3 newsletter research → specifics-bank ekstern bindings (priority 3)

• Seam: before an external research finding persists as an ekstern binding (scripts/specifics-bank/src/kilder.ts:51-52).
• Wiring: screen_output on the claim text + source; FAIL_SECURE → quarantine, surface to the operator in the fact-check sweep the newsletter pipeline already runs.

5.4 analytics CSV import — the container-layer gate (priority 4)

• Seam: saveBatch in scripts/analytics/src/utils/storage.ts:143-160 (or in parseLinkedInCSV).
• Wiring: row-content scan (CSV formula-injection = + - @, active-content) complementing the existing filename-only sanitization (sanitizeDate/Id/Week/Month + verifyPathWithinDirectory, storage.ts:110-137). Lower priority: origin is first-party and the JSON is never re-emitted to a spreadsheet, so the practical blast radius is small — but there is currently no row-content sanitization layer, so it is a real (if narrow) gap.

6. The prepare_input caveat (honest scope of what we can wire)

The input-side bookend (sanitize + fence before the model, contract steps 1–2) has no clean code seam here: the untrusted content is fetched by the model's WebFetch tool and transformed by the drafting agent within the same model turn, so plugin code never holds the raw input to wrap. Partial mitigations exist — a sanitize pass on fetched text inside the URL commands' prompts, or reading tool_input.content in content-gatekeeper for the Write-tool draft path — but neither is the clean prepare_input(untrusted) call the library assumes. What we can wire cleanly and fully is screen_output at the persist gates (§5).

Partly, the contract's real security already holds structurally: the drafting agents largely reason over fetched text (close to "tool-less transform"), and the persist step is a deterministic CLI ("output as data, parsed to a schema"). The lexicon/entropy scan is defense-in-depth on top of that, not the wall.

7. Python ↔ Node interop — the real integration cost

The guard is Python (stdlib, 3.10+). This plugin's runtime is Node ESM .mjs hooks (deliberately zero-npm-dep) + TypeScript engine via tsx. The only Python in the repo is one build-time script (hooks/scripts/compile-hooks.py), never on a data path. So wiring the guard means crossing a subprocess boundary. Options:

Option	Shape	Trade-off
(a) spawnSync('python3', …) at the engine CLI write points (recommended)	The scripts/{trends,brain,specifics-bank,analytics} CLIs (already tsx, not the zero-dep hook hot path) shell out to a python -m llm_ingestion_guard scan	Adds a python3 + pip install llm-ingestion-guard runtime dependency to the engine layer only; keeps the zero-dep Node hooks untouched. Cleanest fit.
(b) Port minimal sanitize + scan_output to a .mjs twin	Reimplement in Node	Defeats the point of adopting a maintained guard; the coverage matrix (126/126) would not apply to the port. Rejected unless a hard no-Python constraint appears.
(c) Bash step inside the command, not the hook	Command invokes the scan before the CLI write	Non-deterministic (depends on the agent running the step); weaker than a code-enforced gate.

Blocker to resolve first: whether a python3 + one-package runtime dependency is acceptable given the plugin's zero-dep design value. This is the gate on any wiring work.

8. OKF import_bundle — future / conditional

The plugin is export-only toward OKF: its brain emits OKF-compatible form (type: + per-level index.md + root okf_version, landed 2026-06-26, docs/okf-convergence-brief.md). There is no import_bundle and no third-party-bundle receive path anywhere in the repo, and inbox auto-classify/convert is explicitly deferred (brief §11). So the guard's okf.import_bundle(bundle, origin=EXTERNAL, channel=AUTOMATIC) adapter has no seam today.

It becomes relevant if/when either lands: (i) SB-S4 — the EU/EEA DMA portability connector auto-feeding ingest/inbox/; or (ii) a cross-plugin shared retrieval skill (a separate standalone plugin, per the convergence brief §8) that merges other plugins' brains. At that point, wire okf.import_bundle at scanInbox with allow_reserved chosen per channel (received bundle → True; materialised individual uploads → False, per brief §4).

9. When — roadmap triggers

1. Now: planned. No wiring. (This doc + the STATE.md marker.)
2. First wiring candidate — trends screen_output (§5.1): the trends→session-reinjection loop is already live, so per the brief's "include it before the first untrusted ingest path goes live," this is the earliest concrete target once §7 is resolved.
3. Hard trigger (not optional) — before SB-S4 or any received-bundle path: the EU/EEA DMA connector, or a cross-plugin shared skill, turns ingest/inbox/ from "user's own manual paste" into an automated external-origin ingress. Wire §5.2 (and §8's import_bundle) before that path goes live — this is the brief's "when, not if" moment.
4. Opportunistic: §5.3 (newsletter) and §5.4 (CSV container-layer) can ride whichever hardening session touches those CLIs.

Sequencing note: none of this is on the current docs/plan-2026-07/ roadmap (N1–N32). It is a new, security-scoped work item to slot in after §7 is decided — most naturally as its own hardening slice, not by displacing the agreed N-plan.

10. Honest limitations (carried from brief §8 — a green scan is not "safe")

• Semantic / factual poisoning is invisible to lexicon + entropy — a plausible-but-wrong concept (wrong metric, wrong runbook step) carries no suspicious token and passes clean. Highest impact for a second-brain. Our existing anti-sycophancy / evidence-threshold / keep-both-timestamped stance in the consolidation loop is the human-in-the-loop mitigation; the deterministic guard does not judge semantics.
• Dormant / broken-link injection: a link to a not-yet-existing target passes a write-time scan; payload planted later. Relevant to the brain's cross-links.
• A document that describes attacks is a false positive — security notes documenting injection payloads trip carrier-strip. Matters if the plugin ever ingests security content.
• Text-only, extracted-text-only — no file parsing in the core; extract text first, scan with high-untrust upload provenance.

11. Existing write-time precedents the guard complements (not replaces)

The plugin already has three narrow write-gate defenses; the guard generalizes the class rather than duplicating them:

• state-updater.mjs uses a replacement function (not string) on every section-append to neutralize $&/$`/$'/$$/$n from $-bearing user topics (:14-25,:117-125) — defends the regex mechanics, not content semantics.
• analytics/storage.ts sanitizes filenames + verifyPathWithinDirectory (:110-137) — path-traversal defense, not row content.
• brain provenance=published — model-collapse guard (authorship), orthogonal to injection (origin).

12. Out of scope for this plan

No guard code, no pip install, no CLI wiring, no hook changes. This is the when/where map and the dependency registration only, per the adoption brief. Implementation is a separate, operator-approved work item gated on §7.