feat(types): privacy pass over a manifest before registry promotion - #7819

Closes #7771.

What this is, and what it deliberately is not

The issue asks for the privacy pass that has to run before an operator-authored agent type can be contributed to librefang/librefang-registry.

I checked what the promotion path actually is on origin/main first, because the issue's premise matters: crates/librefang-api/src/routes/agent_templates.rs registers only GET /templates, GET /templates/{name} and GET /templates/{name}/toml; there is no promote/publish path for an agent type anywhere in crates/ — not in the API, not in librefang-cli (AgentCommands has new / spawn / list / chat / kill / delete / reset-uuid / merge-history / set, no export or publish), and not in librefang-extensions. The only registry-contribution machinery that exists is librefang-skills/src/registry_pr.rs, and it is skill-shaped, not manifest-shaped.

So the endpoint half awaits PR #6931, which adds local POST/PUT/DELETE for agent types. This PR is the primitives plus their tests, wired at the one call site that exists today rather than landed as dead code.

Substance

New module crates/librefang-types/src/manifest_privacy.rs, with the two operations kept separate exactly as the issue asks:

• sanitize_for_publication(&AgentManifest) -> AgentManifest — a publishable copy. Borrows the input and never writes a file.
• scan_for_publication(&AgentManifest) -> Vec<Finding> — what it found, with a bounded single-line preview per finding capped at 96 characters.

The detector is not a diff against the sanitiser. Each Finding carries removed_by_sanitizer: true means confirming publication is enough, false means the value sits inside a field promotion has to keep and the operator must edit it by hand. That second case is the one that matters — nothing structural distinguishes portable configuration from an internal hostname sitting in a system prompt.

Classification

CLASSIFICATION in the module is the readable table; the doc comment carries the per-field reasoning. Summary:

• Stripped — host path: workspace, workspaces (both path and mount describe host layout, and the aliases are often the operator's own vocabulary).
• Stripped — credential binding / private endpoint: model.api_key_env, model.base_url, and the same pair on every fallback_models entry.
• Stripped — host policy: exec_policy, capabilities.shell, capabilities.network, capabilities.ofp_connect, tool_exec_backend, context_engine (plugin names, local Python hook paths, a sidecar endpoint).
• Stripped — operator free text / metadata: context_injection, tools (per-tool params is an untyped operator bag), metadata, model.extra_params and its fallback_models counterpart, channel_overrides, author.
• Stripped — local wiring / state: triggers (target_agent and workflow_id name records on this install), is_hand, enabled.
• Portable: name, version, description, module, schedule, session_mode, model.provider / model.model / system_prompt / sampling knobs, skills, capabilities.tools and the memory / spawn / message grants, mcp_servers, channels, tags, routing, resources, priority, thinking, compaction, profile, tool allow/blocklists, allowed_plugins, response_format, and the remaining behavioural knobs.

Two of those deserve a note because the issue's framing and the code disagree slightly, and the code is right: mcp_servers and channels are names, not bindings — MCP endpoints and headers, and channel tokens and chat ids, live in KernelConfig, never in a manifest. Stripping them would remove the reproducibility the type exists for while protecting nothing, so they travel. Conversely author is stripped even though the issue does not list it: an operator's author is routinely a local username or an e-mail address, and attribution for a contribution belongs to the pull request carrying it.

Why the classification cannot silently rot

Three mechanisms, and the first is the one the issue asks for:

1. Compile-time. sanitize_for_publication destructures AgentManifest with no .. rest pattern and rebuilds it with no ..Default::default(). Adding a field to AgentManifest is therefore an E0027 ("pattern does not mention field") on the destructure and an E0063 ("missing field in initializer") on the construction, in this module, until someone names it on both sides and so decides what happens to it. The same holds for ModelConfig, FallbackModel and ManifestCapabilities, the three types whose interiors are reduced rather than kept or dropped whole. This is the mechanism the issue's "prefer an exhaustive match" asks for — a struct destructure without .. gives the identical guarantee for a struct that a match without a wildcard arm gives for an enum.
2. Runtime, for the readable table. classification_covers_every_serialized_manifest_field asserts CLASSIFICATION and the serialized struct agree in both directions, so the table cannot fall behind the struct and a rename cannot leave a stale entry. The fixture populates every field carrying skip_serializing_if so all 58 keys are emitted.
3. By construction, for the detector. The retained-value scan walks the serialized publishable manifest rather than a list of field names, so a newly added portable field is scanned for pasted secrets from the moment it exists — no third place to update.

Value-level scanners

The credential and PII shapes reuse librefang_types::taint's existing denylist through TaintSink::net_fetch() (the sink that blocks Secret and Pii) rather than growing a second copy. Two adjustments were needed:

• The taint rules for well-known prefixes and opaque tokens anchor on the whole payload, so a key pasted mid-sentence is scanned token by token as well.
• OpaqueToken is skipped for values with no unbroken alphanumeric run of 20 or more characters. Without that gate it fires on every long model id — accounts/fireworks/models/llama-v3p1-405b-instruct and claude-sonnet-4-20250514 both top out at eight — and a detector that cries wolf on model.model teaches the operator to click through the findings that matter. There is a test pinning that specifically.

Absolute-host-path and private-endpoint detection are new here. Both are documented as best-effort with their gaps stated: the POSIX path rule requires a known filesystem root, which means /api/v1/messages in a prompt is not reported and neither is a path under a non-standard root like /nvme0/agents/; the private-endpoint rule covers loopback, RFC 1918 and link-local literals (four octets required, so 10.0.0 is not read as an address), the .local / .internal / .lan / .corp family, and a single-label host behind an explicit scheme.

Wiring

GET /api/templates/{name} gains an additive, read-only promotion_preview object: findings, requires_review (any finding the sanitiser cannot handle on its own), and manifest_toml — the scrubbed manifest, so an operator can attach it to a registry pull request by hand today. manifest_toml is null if the publishable copy cannot be rendered as TOML, with a WARN; that is not a reason to withhold the findings, which are the part that protects the operator.

Nothing existing changes: the raw manifest_toml at the top level is still the operator's file verbatim, and there is a test asserting that. The dashboard consumes only /templates/{name}/toml, so nothing in the SPA is affected and no locale strings are added.

Verification

• cargo test -p librefang-types --lib manifest_privacy — 34 passed. Includes one test per stripped category asserting the value does not survive; no_planted_sentinel_survives_promotion, which greps the serialized publishable manifest for all 19 planted sentinels at once; portable_fields_survive_promotion and portable_collections_survive_promotion for the benign half; classification_covers_every_serialized_manifest_field; sanitizing_does_not_mutate_the_caller_s_manifest; publishable_manifest_round_trips_through_toml; detector_does_not_mistake_a_model_id_for_a_credential; detector_output_is_stable_across_runs; previews_are_bounded_and_single_line; and shape-rule tables with both positive and negative cases.
• cargo test -p librefang-api --test profiles_templates_routes_integration — 13 passed, 4 of them new #[tokio::test]s against the real router: the findings shape, the scrubbed-TOML round trip (host specifics absent, portable half present, raw file unmodified), a secret inside a retained system prompt setting requires_review, and silence on an already-portable template.
• cargo check -p librefang-api --lib — clean.

Not run: cargo clippy. Free space on the build host dropped from 45 GiB to 2.4 GiB during these runs (the shared target directory is contended by other concurrent sessions), so I stopped building rather than risk the machine and am relying on CI for the clippy gate.

One environment note for anyone reproducing locally: librefang-api cannot compile from a fresh worktree without crates/librefang-api/static/react/ existing, because include_dir! panics on the missing directory. I created a gitignored placeholder; it is not part of this diff.

Deferred

Only the half that cannot exist yet: there is no promotion endpoint or CLI command to gate, so nothing calls sanitize_for_publication on the way to a registry. Once #6931 lands its POST/PUT/DELETE, the promote path is scan_for_publication → show the operator the findings → confirm → sanitize_for_publication → the registry_pr.rs-shaped GitHub flow. I have not started that here because it would be guessing at #6931's shape.