[italic-jinxin]

Summary

• Lands the full Reborn-side host port of the v1 WebUI / Web Gateway as a
  native Path A surface (docs/reborn/how-to-port-channel-to-reborn.md).
• Composition layer: webui_v2_app(bundle, config) -> Router with
  descriptor-driven body limits, per-(route, caller) sliding-window
  rate limits, bearer + ?token= (SSE only) auth, CORS, static security
  headers (nosniff / DENY / CSP), and descriptor-driven WebSocket
  same-origin enforcement with operator-supplied canonical_host.
• Host-owned serve crate (ironclaw_reborn_webui_ingress): binds the
  TCP listener and drives axum::serve with graceful shutdown — the
  product/API composition crate stays off the listener-binding boundary
  enforced by reborn_product_api_crates_do_not_bind_http_ingress.
• Three concrete WebuiAuthenticator implementations: env-bearer (with
  subtle::ConstantTimeEq), session-backed (pluggable SessionStore
  trait + in-memory impl with expiry sweep), and OIDC ID-token verifier
  (jsonwebtoken + JWKS cache with single-flight refresh + asymmetric
  algorithm allowlist).
• ironclaw-reborn serve now actually serves: reads [webui] config
  section, mints the v2 Router, and runs the listener with Ctrl-C
  graceful shutdown. Warns loudly when bound to a non-loopback address.
• Three new v2 routes round out the entrypoint inventory: thread list
  (GET /api/webchat/v2/threads), WebSocket transport variant of
  stream-events (GET .../ws, same-origin enforced inline because WS
  upgrades skip CORS pre-flight), and extensions onboarding
  (POST /api/webchat/v2/extensions/{name}/setup, skeleton returning
  NotImplemented until a v2-aware extension lifecycle lands).

Change Type

• New feature (feature-gated webui-v2-beta, off by default)
• Security (gateway middleware composition + host auth)

Linked Issue

Closes #3580.

The Path A native-host-surface checklist on #3580 is satisfied:
inventory ✅, auth (bearer/DB/OIDC) ✅, query-token + CSRF/origin
(WS same-origin) ✅, CORS ✅, body/rate/connection limits ✅, static
security headers ✅, browser submissions → ProductWorkflow ✅, native
replies/progress/projections (SSE + WS) ✅, caller-level tests for
submission and streaming/projection ✅, parity docs ✅.

Validation

• cargo fmt --all -- --check
• cargo clippy --workspace --all-targets --features webui-v2-beta -- -D warnings
• cargo build --bin ironclaw (v1 binary still builds, untouched)
• Relevant tests pass:
  • cargo test -p ironclaw_reborn_webui_ingress — 13 unit + 3 integration
    (real listener bind / serve / graceful shutdown / bind error / EnvBearer
    accept-reject-prefix-empty / Session create-lookup-expired-unknown / OIDC
    audience-exp-nbf-mapper-rejects).
  • cargo test -p ironclaw_reborn_composition --features webui-v2-beta —
    21 caller-level integration tests including: bearer happy-path,
    missing/invalid bearer, SSE ?token=, timeline rejects ?token=,
    static headers, CORS allow + reject, descriptor body-limit 413,
    in-budget mutation reaches facade, NoBody body rejection,
    rate-limit 429 + per-caller independence, list-threads, setup-extension
    skeleton, WS upgrade happy-path (101) via tokio-tungstenite, and
    WS canonical_host override of forged Host.
  • cargo test -p ironclaw_webui_v2 --features webui-v2-beta —
    14 handler-contract + 1 descriptor-contract tests; route table
    locked at 9 routes.
  • cargo test -p ironclaw_architecture reborn — 12 boundary tests
    pass, including reborn_product_api_crates_do_not_bind_http_ingress
    (new ingress crate is the only one allowed to bind a listener) and
    reborn_cli_binary_crate_stays_separate_from_v1_root.
• cargo test --features integration — not applicable (no DB schema
  change, no integration tier behavior).
• Manual: no browser session yet; full pipe-through is exercised by the
  real-listener WS upgrade test and tokio-tungstenite round-trip.

Security Impact

This is a Track C change. Security-relevant properties pinned by the
gateway:

• Auth. Bearer-only on mutation/read; ?token= shim ONLY on the
  SSE event route (browser's EventSource can't set headers).
  Authenticator None → 401 before facade. Three concrete authenticators
  shipped:
  • EnvBearerAuthenticator — constant-time comparison via
    subtle::ConstantTimeEq; rejects empty configured token at
    construction.
  • SessionAuthenticator — pluggable SessionStore trait. In-memory
    impl included; sweeps expired sessions on every create/lookup so a
    long-running process cannot leak memory. Production deployments
    wire their own durable store.
  • OidcAuthenticator — JWKS with TTL cache + tokio::sync::Mutex
    single-flight refresh; asymmetric algorithms only (RS256/384/512,
    ES256/384) — symmetric HS* explicitly rejected so a stolen shared
    secret cannot forge tokens; defense-in-depth iss/aud/exp/nbf checks
    after jsonwebtoken's own validation.
• Caller identity. WebUiAuthenticatedCaller built from
  config.tenant_id (host-trusted installation config) plus the
  authenticator's verified UserId. Browser body cannot influence
  either field.
• CORS. Allow-origin = config.allowed_origins; empty list →
  fail closed, never echoes attacker-supplied Origin.
• WebSocket same-origin. WS upgrades bypass CORS pre-flight, so
  the same-origin check runs inline on every WS request whose
  descriptor declares WebSocketOriginPolicy::SameOriginRequired.
  Optional canonical_host config defends against
  reverse-proxy-passthrough-Host attacks by comparing Origin
  against the operator-trusted value instead of trusting the
  client-supplied Host header.
• Body limits. Descriptor-driven per route (create_thread 16 KiB,
  send_message 1 MiB, cancel_run / resolve_gate / setup_extension
  4 KiB / 16 KiB, get_timeline / stream_events / WS NoBody). Outer
  14 MiB fallback for unmatched paths.
• Rate limits. Descriptor-driven sliding window per (route, caller). Mutation 60/60, read 120/60, stream 12/60. Composition
  fails closed for unsupported RateLimitScope values
  (webui_rate_limit::tests::unsupported_scope_is_rejected_at_composition).
• Connection limits. SseCapacity (3 streams per (tenant, user),
  5-min stream lifetime) applies to both SSE and the new WS route.
• Static headers. nosniff, DENY, default CSP
  default-src 'self'; object-src 'none'; frame-ancestors 'none'; base-uri 'self'.
• Listener boundary. reborn_product_api_crates_do_not_bind_http_ingress
  is unchanged. New ironclaw_reborn_webui_ingress crate is the only
  permitted place for axum::serve / TcpListener::bind; product/API
  crates (composition, webui_v2, product_workflow, etc.) still cannot
  bind sockets.
• Fail-closed defaults. SessionThreadService::list_threads_for_scope
  default impl now returns Err(Backend(...)) instead of fabricating an
  empty thread list — backends that don't implement enumeration surface
  503 to the client instead of pretending zero threads exist.
• Non-loopback bind warning. ironclaw-reborn serve emits a stderr
  WARNING + tracing::warn! when binding to a non-loopback interface,
  to catch operator footguns.

Reborn Trust-Boundary Checklist

• Public policy/evidence/trust-bearing types — WebuiServeConfig,
  WebuiAuthenticator, SessionStore, OidcAuthenticator are all
  host-owned. WebUiAuthenticatedCaller comes from
  ironclaw_product_workflow and is built by composition's bearer
  middleware from trusted config tenant + verified user.
• Untrusted content into prompts — N/A, gateway layer doesn't reach
  into prompts.
• Hashes declare purpose — N/A, no new hashing.
• New error variants audited: WebuiServeError, WebuiServeConfigError,
  RateLimitConfigError, SessionStoreError, OidcAuthenticatorError,
  RebornWebuiServeError. Match sites local to this PR; downstream
  callers wrap via ?. Command: rg "WebuiServe|RateLimitConfig|SessionStoreError|OidcAuthenticatorError|RebornWebuiServeError" --type rust.
• Security serde(default) audit: WebUiSetupExtensionRequest.extension_name
  is #[serde(default)] so the path-bound name (host-trusted route param)
  cannot be overridden by a body field. Verified the handler always
  overwrites with the path-bound value before forwarding to the facade.
• Bounded buffers — rate-limit LRU 8192 entries; session map sweeps
  expired records on every touch; body buffer per-route ≤ 1 MiB; WS
  buffer reuses SSE drain bounds.
• Stable error classes — RebornServicesError already classes
  (NotFound / Conflict / InvalidRequest / Internal / RateLimited /
  ServiceUnavailable). New Backend failures from list_threads_for_scope
  default route through service_unavailable(true) (503 retryable).
• Sandbox / native / host naming accurate — ironclaw_reborn_webui_ingress
  is host-owned ingress, named accordingly; composition stays a
  product/API library.

Database Impact

None. No schema, migration, or DB-touch in this PR. SessionStore is a
trait with an in-memory impl; durable backends (Postgres / libSQL) are
follow-up work.

Blast Radius

• Touched crates (all Reborn-side): new
  ironclaw_reborn_webui_ingress; modifications to
  ironclaw_reborn_composition, ironclaw_reborn_cli,
  ironclaw_reborn_config, ironclaw_product_workflow,
  ironclaw_threads, ironclaw_webui_v2, ironclaw_architecture (test
  allowlist).
• v1 surface untouched. /src/, channels-src/, migrations/,
  root tests/*.rs — zero file changes. v1 binary (ironclaw)
  builds clean. v1 doesn't import any new trait / type from this PR
  (verified via grep).
• Trait additions are backward-compatible.
  SessionThreadService::list_threads_for_scope has a default impl, so
  existing impls don't need to change. RebornServicesApi::list_threads /
  setup_extension are required methods, but the trait is in
  ironclaw_product_workflow which v1 cannot depend on (architecture
  rule).
• Wire-format relaxations only. WebUiSetupExtensionRequest.extension_name
  changed required → #[serde(default)]. Accepts more inputs; the path
  binding always overwrites.
• Could surprise. A [webui] config section with malformed entries
  fails closed at parse time via secrets_guard::reject_inline_secret.
  Missing IRONCLAW_REBORN_WEBUI_TOKEN / IRONCLAW_REBORN_WEBUI_USER_ID
  env vars fail serve startup with a clear error, never start a
  serve loop with auth disabled.

Rollback Plan

The whole surface is feature-gated by webui-v2-beta (off by default).
Rollback is:

1. Revert the merge commit. v1 binary behavior is unchanged regardless
   (no v1 file touched).
2. If a downstream host turned on webui-v2-beta in its Cargo.toml,
   remove that feature line; the non-beta build path of
   ironclaw_reborn_composition is identical to pre-PR.
3. No DB migration to reverse. No on-disk schema introduced. Operator
   ~/.ironclaw/reborn/config.toml keeps parsing fine without [webui].

The standalone ironclaw-reborn serve subcommand is the only place
this code runs today (no v1 binary serves v2 traffic), so revert is
safe at any time.

Review Follow-Through

• Pre-existing test failure unrelated to this PR:
  ironclaw_reborn_composition::runtime::tests::local_dev_runtime_wires_input_skill_context_source_to_model_calls
  fails on RebornRuntimeInput.services must include a resolved runtime policy. Verified this exact failure exists on the parent merge
  commit before any of this PR's changes; left as-is.
• Skeleton implementations acknowledged in code:
  • SessionStore ships with an in-memory impl only — durable
    Postgres / libSQL backends are explicit follow-up.
  • RebornServicesApi::setup_extension returns
    RebornSetupExtensionStatus::NotImplemented because the v1
    extension onboarding controller is intentionally not ported (per
    "do not touch v1" constraint). The route exists so the v2 entrypoint
    inventory is complete and the host facade has a stable surface for
    future onboarding work.
  • SessionThreadService::list_threads_for_scope default impl returns
    Err(Backend). Existing impls (InMemorySessionThreadService,
    FilesystemSessionThreadService) don't override yet, so the
    /api/webchat/v2/threads route returns 503 until a backend wires
    real enumeration. Fail-closed by design.

---

Review track: C (security/runtime gateway, feature-gated, host
auth + composition).

[gemini-code-assist]

Code Review

This pull request introduces the Reborn WebChat v2 native surface to the gateway, gated by the webui-v2-beta feature. It adds the necessary dependencies, updates the GatewayState to include v2 composition, and integrates a new v2 router into the protected route tree. A new middleware, inject_webui_v2_caller, is implemented to adapt the existing UserIdentity for v2 handlers. Extensive documentation and integration tests are included to verify security invariants such as CORS, static headers, and query-token authentication for SSE. Review feedback suggests refactoring the middleware's identity extraction to use the more idiomatic let-else construct for improved readability.

[serrrfirat]

Please do not change channel behaviour in v1. There is a separate binary for reborn, changing channel behaviour in /src will not effect the reborn binary

[serrrfirat]

Do not change /src or v1 binary

[serrrfirat]

Reviewed against #3580 and the Path A porting guide. The shape is right: keeping WebUI v2 as a native host-owned Reborn surface, avoiding ProductAdapter/protocol-auth shims, and stopping this product/API crate at Router is the right boundary. The caller-level router tests for bearer auth, SSE ?token=, CORS, headers, and per-caller rate limiting are also the right kind of proof.

A few things I want addressed before this lands.

1. Descriptor body limits are part of the host ingress contract, but this composition only enforces a global 14 MiB cap.

ironclaw_webui_v2::webui_v2_routes() declares the production policy surface: create-thread is 16 KiB, send-message is 1 MiB, cancel/resolve are 4 KiB, and timeline/SSE are NoBody. webui_v2_app reads those descriptors for rate limits, but then applies only RequestBodyLimitLayer::new(config.max_body_bytes) across the whole router. That lets authenticated clients send bodies well above the descriptor contract and still reach handler parsing.

Please make body-limit resolution descriptor-driven in the same spirit as rate limiting, including fail-closed behavior for unsupported body policy shapes. A good regression would drive the composed webui_v2_app with an oversized create-thread/send-message body and assert the facade is not called; also cover NoBody routes if the chosen middleware can observe that.

2. This should not close #3580 as written.

#3580 tracks the whole native WebUI/Web Gateway port: preserving auth/query-token exceptions, CSRF/origin, CORS, body/rate/connection limits, static headers, mapping submissions, keeping replies/progress/projections native, and caller-level tests for submission and streaming/projection behavior. This PR lands the composition-library slice and is honest in the body that ironclaw-reborn serve wiring, browser reachability, concrete env/DB/OIDC authenticators, WebSocket, thread list, and onboarding are not in scope. Merging with Closes #3580 would close the tracker while several checklist items remain intentionally open.

Please change this to Advances #3580 (or link a narrower issue that this fully closes) and name the follow-up issue/branch for host-side serve/auth wiring.

Smaller items:

• Add the unsupported rate-limit scope regression noted inline. That fail-closed path is the guard that keeps future descriptor changes from silently weakening enforcement.
• Fill in the PR template's Security Impact, Blast Radius, Rollback Plan, and actual validation commands. This is a Track C-shaped gateway/security change even if it is feature-gated and not yet browser-mounted.

Net: the boundary and native-surface direction are sound, but descriptor body-limit enforcement and issue-scope honesty need to be fixed before merge.

[serrrfirat]

Multi-agent review of PR #3815 at d93e92a. Reviewed by Security, Bugs, Performance/Concurrency, Tests, and Conventions lenses, with local aggregation.

Requesting changes because the shipped ironclaw-reborn serve path cannot deliver the advertised SSE/WS projections, and there are several security/runtime follow-ups around session secrecy, OIDC refresh throttling, and long-lived WS slots.

Findings posted inline:

• High: CLI serve builds WebUI services with no projection stream, so /events and /ws never provide native progress/projections.
• Medium: session records duplicate the bearer token in a public serializable/debuggable struct.
• Medium: unknown JWT kid values can force repeated JWKS refreshes before authenticated rate limits apply.
• Medium: idle closed WebSockets are not observed until send/error/max lifetime, holding stream slots and polling backend.
• Medium: serve rejects configs with [identity].default_project before applying the WebUI project scope it parses later.
• Medium: session backend lookup errors collapse silently to auth miss with no operator evidence.
• Low: [webui].listen_port = 0 from config binds an undiscoverable ephemeral port while the banner still prints port 0.

Additional nonblocking coverage gaps from the Tests lens: add concrete RebornServices::list_threads success and missing-agent contract tests, plus a handler test proving ?limit=&cursor= reach the facade. I did not inline those because the runtime defects above are the merge blockers.

[think-in-universe]

@copilot resolve the merge conflicts in this pull request

[Copilot]

@copilot resolve the merge conflicts in this pull request

Resolved. I merged origin/reborn-integration into this branch and fixed the merge conflicts; merge commit: b4ae5ae0.