docs: define custom provider security boundary

[steipete]

Summary

• define a bounded config-only custom HTTP JSON provider MVP
• document the required runtime ProviderInstanceID seam before arbitrary provider instances can coexist safely
• specify endpoint, redirect, full-URL approval, secret, transport-isolation, response-size, mapping, redaction, and persistence boundaries
• list exact non-goals, threat model, staged implementation slices, required proof, and owner decisions

Recommendation

Approve the security boundary and a separate identity-seam spike. Keep custom-provider networking disabled until the identity migration and pure transport/evaluator tests land independently. If the identity migration is too broad, close #1735 as unsupported rather than adding one shared .custom slot or a parallel UI path.

Validation

• make docs-list
• swift test --filter 'StatuspageSummaryTests|GoogleWorkspaceStatusTests|UsageStoreCoverageTests' (35 tests)
• make check
• make test
• /Users/steipete/Projects/agent-skills/skills/autoreview/scripts/autoreview --mode local ...

No runtime behavior, provider auth, config version, or release metadata changes in this PR.

Issue #1735 intentionally remains open for owner acceptance and implementation follow-up.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed July 1, 2026, 4:19 AM ET / 08:19 UTC.

Summary
Adds docs/custom-provider-design.md defining a config-only custom HTTP JSON provider MVP, ProviderInstanceID identity seam, security/network/mapping boundaries, staged proof, and owner decisions.

Reproducibility: not applicable. This PR adds a design document and no runtime behavior. Source inspection confirms current main still uses fixed provider IDs and fixed config fields.

Review metrics: 1 noteworthy metric.

• Docs-only surface: 1 file added, 0 runtime files changed. This matters because the PR defines future security guidance without enabling custom-provider networking or changing provider auth behavior.

Root-cause cluster
Relationship: partial_overlap
Canonical: #1735
Summary: This PR is a design-boundary companion to the open custom-provider feature issue, not the implementation of that feature.

Members:

• canonical: [Feature] Declarative "Custom Provider": bring-your-own endpoint + JSONPath field mapping #1735 - The issue is the open feature request for declarative custom providers, and the PR body/comment state that it intentionally remains open for owner acceptance and implementation follow-up.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🦞 diamond lobster
Proof: 🌊 off-meta tidepool
Patch quality: 🦞 diamond lobster
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Risk before merge

• [P1] The document leaves owner decisions open, so merging it should be treated as accepting a design boundary, not as approval to enable custom-provider networking.

Maintainer options:

1. Decide the mitigation before merge
   Land the doc only if maintainers accept it as the boundary, then keep implementation tracked under [Feature] Declarative "Custom Provider": bring-your-own endpoint + JSONPath field mapping #1735 with separate identity-seam, evaluator, and transport slices before enabling networking.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• [P2] Needs maintainer/owner acceptance of the design boundary, not an automated code repair.

Security
Cleared: The diff is docs-only and does not change runtime code, dependencies, secret handling, network behavior, or supply-chain inputs.

Review details

Best possible solution:

Land the doc only if maintainers accept it as the boundary, then keep implementation tracked under #1735 with separate identity-seam, evaluator, and transport slices before enabling networking.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this PR adds a design document and no runtime behavior. Source inspection confirms current main still uses fixed provider IDs and fixed config fields.

Is this the best way to solve the issue?

Yes for a docs-only boundary: the proposal is narrow because it explicitly keeps networking disabled and gates implementation on identity, evaluator, transport, approval, and proof work. Final product acceptance still belongs to maintainers.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against d3f2d6433026.

Label changes

Label changes:

• add P3: This is low-risk design documentation for a speculative provider extensibility feature, not a broken current workflow.
• add rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🌊 off-meta tidepool and patch quality is 🦞 diamond lobster.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: Real behavior proof is not required because this PR only changes files under docs/.

Label justifications:

• P3: This is low-risk design documentation for a speculative provider extensibility feature, not a broken current workflow.
• rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🌊 off-meta tidepool and patch quality is 🦞 diamond lobster.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: Real behavior proof is not required because this PR only changes files under docs/.

Evidence reviewed

What I checked:

• PR metadata: GitHub reports this PR as open, mergeable/clean, authored by steipete, and changing one added docs file with no reviews yet. (10fd48654028)
• Docs-only design status: The added document states that it is an owner-decision-required boundary document and does not authorize or implement the feature. (docs/custom-provider-design.md:11, 10fd48654028)
• Security boundary content: The proposal includes explicit URL/auth, redirect, approval, redaction, transport isolation, response-size, and local-config-only requirements for any future custom provider networking. (docs/custom-provider-design.md:124, 10fd48654028)
• Identity migration gate: The document requires a separate ProviderInstanceID seam before any custom network path, preserving first-party provider IDs and preventing shared custom-provider state. (docs/custom-provider-design.md:154, 10fd48654028)
• Current provider IDs are closed: Current main still models provider identity as the fixed Codable UsageProvider enum, which supports the document's claim that runtime identities need a separate migration. (Sources/CodexBarCore/Providers/Providers.swift:5, d3f2d6433026)
• Current config remains first-party shaped: Current main config is version 1 and ProviderConfig requires a UsageProvider id with fixed provider fields, not arbitrary request/mapping definitions. (Sources/CodexBarCore/Config/CodexBarConfig.swift:96, d3f2d6433026)

Likely related people:

• steipete: Current-main blame for UsageProvider, ProviderConfig, ProviderDescriptorRegistry, and ProviderEndpointOverrideValidator points to Peter Steinberger, and he authored this design PR plus the linked owner follow-up comment. (role: central provider/config owner and current design author; confidence: high; commits: f380287041b8, 10fd48654028; files: Sources/CodexBarCore/Providers/Providers.swift, Sources/CodexBarCore/Config/CodexBarConfig.swift, Sources/CodexBarCore/Providers/ProviderDescriptor.swift)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.