feat(reborn): add product adapter host auth and egress primitives

[serrrfirat]

Split from #3316 (original PR by @nickpismenkov). This is PR 2/7 in the ProductAdapter stack.

Summary

• Add ironclaw_wasm_product_adapters host auth/egress primitive crate.
• Add constant-time HMAC/shared-secret webhook auth verifiers.
• Add declared-host + credential-handle egress policy.
• Add initial wit/product_adapter.wit shape.
• Intentionally excludes runner glue and Telegram behavior.

Stack

• Depends on feat(reborn): add product adapter contract #3351.
• Base branch: split/pr3316-01-product-adapter-contract.

Authorship

Split commits retain Co-authored-by: Nikolay Pismenkov <nickpismenkov@gmail.com>.

Verification

• cargo test -p ironclaw_wasm_product_adapters --offline --quiet — 13 tests passed on this slice.
• Final stack also ran cargo fmt --all -- --check and targeted ProductAdapter/Telegram/config tests.

[gemini-code-assist]

Code Review

This pull request introduces the ironclaw_wasm_product_adapters crate, which establishes the host runtime primitives for WASM v2 product adapters, focusing on protocol authentication and egress policy enforcement. Key components include HMAC and shared-secret verifiers, an egress allow-list mechanism, and the WIT contract defining the component model boundary. The review feedback identifies several improvement opportunities: enhancing the robustness of system clock handling by avoiding default values, improving type safety for timestamp parsing through newtypes, refining error handling with specific variants and structured logging, and utilizing a standard crate for hex encoding instead of a custom implementation.

[gemini-code-assist]

Using unwrap_or(0) for duration_since(UNIX_EPOCH) can mask potential issues if the system clock is set to a time before the Unix epoch. Following repository rules, if a timestamp is unknown or invalid, treat it as un-reapable by logging a warning and skipping the operation. Do not fall back to a default value like 0, as this can cause the resource to perpetually appear new and prevent proper cleanup or validation.

References

1. When calculating resource age or timing, if the timestamp is unknown, log a warning and skip it instead of falling back to a default value.

[gemini-code-assist]

The now_unix_seconds method returns u64, but timestamp_str.parse::<i64>() parses the incoming timestamp as i64. To align with the 'Parse, Don't Validate' approach, consider using a newtype wrapper or parsing directly into the target type (u64) at the boundary to ensure type safety and consistency.

References

1. Prefer creating a newtype wrapper that validates on construction to ensure type safety and centralize validation at system boundaries.

[gemini-code-assist]

The error handling for Hmac::<Sha256>::new_from_slice currently treats any unexpected error as ProtocolAuthFailure::Malformed. Per repository rules, create specific error variants for different failure modes. Additionally, ensure detailed errors from external dependencies are logged using a structured logger (like tracing) while returning a sanitized error to the caller.

References

1. Create specific error variants for different failure modes to provide semantically correct and clear error messages.
2. Log detailed errors from external dependencies using structured logging while returning sanitized errors to callers.

[gemini-code-assist]

This module implements a custom hex::encode function. For consistency, security, and maintainability, it's generally recommended to use a well-vetted external crate like the hex crate. Re-implementing such utility functions, especially in a security-sensitive context, can introduce subtle bugs.

pub use hex::encode;

[gemini-code-assist]

To use the hex::encode function from the hex crate as suggested in auth_verifier.rs, you need to add hex = "0.4" to the [dependencies] section of this Cargo.toml file.

Suggested change

	uuid = { version = "1", features = ["v4", "serde"] }
	uuid = { version = "1", features = ["v4", "serde"] }
	hex = "0.4"

[ilblackdragon]

Code Review: PR #3352 — feat(reborn): add product adapter host auth and egress primitives

Where this fits in the Reborn integration

This PR adds the WASM v2 product-adapter trust boundary — webhook auth verification and constrained egress — for the upcoming WASM-based product adapters (Slack, Telegram, etc., as components rather than native Rust). Recall the broader stack:

Webhook delivery (Slack/Telegram/Discord)
  ↓ host glue
[1] WebhookAuthVerifier (THIS PR)              ← HMAC / shared-secret check
  ↓ verified → mint sealed VerifiedAuthClaim (host_only seal in ironclaw_product_adapters)
WASM ProductAdapter component (future PR)
  ↓ parse-inbound(raw_payload, evidence) → ParsedProductInbound
host glue stamps ProductInboundEnvelope
  ↓
DefaultProductWorkflow (#3428)
  ↓ TurnCoordinator → scheduler (#3438) → host (#3439) → driver → exit (#3446)

The trust seam: WASM cannot mint Verified evidence — the seal type is unreachable inside the component. The host minting is gated by feature flags (host-auth-mint, test-support).

The WIT file in this PR documents the eventual component contract; the bindgen wiring lands in a later PR ("the WIT below is the agreed shape for the eventual component build").

Strengths

• Constant-time comparison everywhere. Both HmacWebhookAuth and SharedSecretHeaderAuth use subtle::ConstantTimeEq. No timing oracles. ✅
• Symmetric replay window. HMAC verifier rejects timestamps drifted in either direction ((now_secs - timestamp_secs).abs() > max_age) — both stale captures and far-future forgeries fail. Default 5 min matches Slack convention.
• Clock seam. Clock trait + SystemClock + FixedClock makes time-window tests deterministic. The verifier_at(now_secs, max_age_secs, secret) test helper produces clean timestamp-window tests.
• Architecture boundary tests are exemplary. Three of them:
  • wasm_product_adapter_crate_has_local_guardrails — CLAUDE.md must exist.
  • wasm_product_adapter_crate_keeps_minimal_host_glue_dependencies — pins the exact dep list [hmac, http, ironclaw_product_adapters, sha2, subtle, thiserror]. Adding any new dep requires explicit test update.
  • wasm_product_adapter_wit_preserves_product_adapter_trust_boundary — greps the WIT file for required record names AND forbidden ones (record parsed-envelope, envelope-json, Returns \none`, ProductInboundEnvelope`). Locks the trust contract at the WIT layer. Excellent regression scaffolding.
• EgressPolicy is fail-closed. Undeclared host → error; unknown credential handle → error. Tests cover both paths. The "declared host with known handle passes" test confirms the success path.
• WIT design is conservative. Egress responses don't expose raw headers (!response_record.contains("headers") test). host-index: u32 and credential-handle-index: option<u32> mean the component only sees indices into a host-controlled allowlist — no raw URLs. log and now-millis are the only general-purpose imports — no filesystem, no env, no random.

Issues

Typed-internals (.claude/rules/types.md)

• EgressPolicy stores BTreeSet<String> instead of BTreeSet<DeclaredEgressHost> / BTreeSet<EgressCredentialHandle> (egress_policy.rs:773-775). Constructor takes typed values and immediately drops to String via .as_str().to_string(). Same anti-pattern as in feat(reborn): add text-only loop driver host factory #3439 / feat(reborn): add ProductWorkflow and InboundTurnService facade (#3280) #3428 — typed values are validated, then thrown away inside the policy. Storing the typed values keeps the validated invariant alive across lookups and would let declared_hosts() return impl Iterator<Item = &DeclaredEgressHost> instead of &str. Fix:

  pub struct EgressPolicy {
      declared_hosts: BTreeSet<DeclaredEgressHost>,
      allowed_credential_handles: BTreeSet<EgressCredentialHandle>,
  }

• EgressPolicyError::UndeclaredHost { host: String } / UnauthorizedCredentialHandle { handle: String }. Errors are at the boundary so this is forgivable (they go to logs/wire), but the typed values exist — carrying them in the error struct preserves type identity through error propagation. Lower priority than the storage fix above.

Correctness

• HmacWebhookAuth::Hmac::<Sha256>::new_from_slice(&self.signing_secret) only fails on empty key. The comment says "should never reject a non-empty key" — true. But empty keys would hit this path and return ProtocolAuthFailure::Malformed. Add a test for the empty-key case to lock the behavior; an empty signing secret is a configuration bug worth detecting at verify time.
• The hand-rolled hex module uses format!("{byte:02x}") per byte — heap allocation per byte. For 32-byte HMAC digests it's 32 allocs per verify. The hex crate is ~50 LOC and well-audited; consider depending on it (the dep-list test would need updating). Negligible perf at low rates; matters at high webhook volume.
• auth.rs adds 6 #[cfg_attr(not(...), allow(dead_code, reason = "..."))] annotations. A lot of repetition. Either factor into a single module-level #![cfg_attr(...)] if scoping permits, or leave as-is — the reason = "..." field is informative and worth keeping. Note: reason requires Rust 1.81+; verify MSRV.

WIT contract

• evidence: auth-evidence in parse-inbound is just record auth-evidence { evidence-json: string } in WIT — i.e., an opaque JSON string. The architecture comment says "Components cannot mint a verified auth-evidence value" but the WIT doesn't enforce that — the seal lives in the host-side Deserialize impl in auth.rs that rejects verified variants from untrusted JSON. This is correct but invisible to a WIT reader. Add a comment in the WIT block explaining: "// The host serializes only sealed evidence into evidence-json; component-supplied JSON cannot impersonate a verified claim because the host's Deserialize impl rejects unsealed verified variants."

Test coverage

• No test for EgressPolicy round-trip with multiple hosts/handles. Three tests cover single-host, single-handle. A test with two declared hosts where one matches and one doesn't would lock the iteration semantics.
• No test that HmacWebhookAuth::with_max_age(0) rejects all timestamps. Edge case but the symmetric drift check (drift > max_age) means any nonzero drift fails when max_age == 0. A "max_age=0 always rejects" test makes the symmetry explicit.

Risk

risk: medium is right. The crypto is constant-time, the boundary tests are tight, the WIT is conservative. The typed-internals issues are the only blocking items per the rule.

Summary

Approve with these:

1. Store BTreeSet<DeclaredEgressHost> / BTreeSet<EgressCredentialHandle> in EgressPolicy instead of BTreeSet<String> per .claude/rules/types.md.
2. Add a comment in the WIT explaining that the auth-evidence seal lives in the host-side Deserialize impl — the WIT alone doesn't enforce it.
3. Add empty-signing-secret test for HmacWebhookAuth to lock the malformed-config path.
4. Verify Rust MSRV supports reason = "..." in cfg_attr(allow(...)) (1.81+).

The architecture and crypto discipline are excellent. Typed-internals is the cleanup before merge; everything else is polish.

[serrrfirat]

Addressed ilblackdragon review feedback in fbe71d9e:

• Kept EgressPolicy internals typed: BTreeSet<DeclaredEgressHost> and BTreeSet<EgressCredentialHandle>; policy errors now carry typed values too.
• Updated policy iterators to return typed refs and added multi-host/multi-handle coverage for membership + fail-closed paths.
• Added WIT comment explaining auth-evidence.evidence-json is host-serialized sealed evidence and component JSON cannot impersonate verified claims because host-side deserialize rejects unsealed verified variants.
• Added HMAC empty signing-secret coverage; empty secret now fails as malformed config before digest work.
• Added with_max_age(0) drift coverage for the replay-window edge case.
• Removed per-byte format! allocation in the local hex encoder without adding a dependency, preserving the minimal dependency guardrail.
• Verified allow(reason = ...) is supported by current MSRV: workspace/crates use rust-version = "1.92".

Local verification:

• cargo test -p ironclaw_wasm_product_adapters
• cargo test -p ironclaw_product_adapters
• cargo test -p ironclaw_architecture wasm_product_adapter
• cargo fmt --check
• cargo clippy -p ironclaw_wasm_product_adapters -p ironclaw_product_adapters -p ironclaw_architecture --tests -- -D warnings
• bash scripts/pre-commit-safety.sh
• git diff --check

[serrrfirat]

Follow-up complete after the strategy audit.

Updates pushed in d433e52b:

• Merged current reborn-integration into this PR and resolved the workspace-member conflict by preserving the new Reborn crates plus crates/ironclaw_wasm_product_adapters.
• Added an explicit zero-window HMAC test: with_max_age(0) accepts an exact timestamp and rejects any nonzero drift.
• Re-ran local gates against the updated base:
  • cargo test -p ironclaw_wasm_product_adapters
  • cargo test -p ironclaw_product_adapters
  • cargo test -p ironclaw_architecture wasm_product_adapter
  • cargo fmt --check
  • targeted clippy with -D warnings
  • scripts/pre-commit-safety.sh against origin/reborn-integration
  • git diff --check origin/reborn-integration...HEAD
• GitHub checks on current head are green: Code Style, Clippy, Regression enforcement, Reborn CLI smoke, cargo-deny, no-panics, gateway checks, classify/scope.

@ilblackdragon ready for re-review.

[nickpismenkov]

Thanks for the quick re-review, @henrypark133. Pushed 35f29ce1f to address the WIT-manifest pair gap.

You're right that independent declared-egress-hosts / declared-credential-handles lists couldn't express the paired Rust contract — a future host glue would have had to either cross-product them (reintroducing the cross-pair leak) or invent pair metadata the manifest didn't carry. Good catch.

WIT changes

1. New paired record:

   record declared-egress-target {
       host: string,
       credential-handle: option<string>,
   }

   Mirrors ironclaw_product_adapters::DeclaredEgressTarget on the Rust side. credential-handle: none declares an explicit unauthenticated target — the host's EgressPolicy::check now requires the exact (host, None) pair to authorize bare requests, so unauthenticated entries are deliberate, not catch-all.

2. Manifest carries paired targets:

   record adapter-manifest {
       ...
       declared-egress-targets: list<declared-egress-target>,
       declared-auth-requirements: list<auth-requirement>,
   }

   Replaces the prior declared-egress-hosts: list<string> + declared-credential-handles: list<string>.

3. Single index into the paired list:

   record egress-request {
       egress-target-index: u32,
       method: string,
       path: string,
       headers: egress-headers,
       body: list<u8>,
   }

   Replaces host-index: u32 + credential-handle-index: option<u32>. The cross-pair leak shape (slack_token against api.telegram.org) is now impossible to express over the WIT boundary — there's no separate handle index to mismatch the host with. Components select a single declared pair; the host applies both axes from that pair.

4. Updated top-of-file host-invariant block to describe egress in pair terms — the WIT-side documentation of the Rust policy contract.

Boundary test

New wasm_product_adapter_wit_declares_egress_targets_as_paired_records in crates/ironclaw_architecture/tests/reborn_dependency_boundaries.rs:

• Asserts record declared-egress-target and declared-egress-targets: list<declared-egress-target> exist.
• Asserts the single egress-target-index: u32 shape.
• Asserts the prior independent-list / split-index forms (declared-egress-hosts: list<string>, declared-credential-handles: list<string>, host-index: u32, credential-handle-index: option<u32>) are gone — a regression that splits the pair back fails this test loudly.

5 WIT boundary tests now pass (the new one plus the existing 4).

No Rust callers affected

Grep on crates/ and src/ confirms zero references to the removed WIT fields — wasmtime component bindgen is intentionally not wired up yet (per the WIT preamble). This is a contract update with no runtime call-site churn.

Verified

• cargo check --workspace clean
• cargo fmt --all -- --check clean
• cargo clippy -p ironclaw_architecture -p ironclaw_wasm_product_adapters -p ironclaw_product_adapters --all-targets --all-features -- -D warnings zero warnings
• cargo test -p ironclaw_architecture wasm_product_adapter 5 tests green

[serrrfirat]

Pushed 80e5e592 to tighten PR #3352 test coverage after a focused audit.

Added coverage for:

• HMAC auth verifier missing signature and missing timestamp headers (ProtocolAuthFailure::Missing).
• Egress origin-form path rejection, including explicit ://, fragment, backslash, CR/LF, and NUL shapes, plus a valid query-path control case.
• Host-managed identity/proxy headers, including newly-forbidden Forwarded and X-Forwarded-For in addition to the existing host/auth/cookie/forwarded metadata headers.
• Invalid header-name syntax (space, :, /, ., CRLF injection).

Verification:

• cargo test -p ironclaw_wasm_product_adapters — 26 passed
• cargo test -p ironclaw_product_adapters — lib 45 passed, integration suites 20 + 16 passed
• cargo test -p ironclaw_architecture wasm_product_adapter — 5 passed
• cargo fmt --all -- --check
• cargo clippy -p ironclaw_wasm_product_adapters -p ironclaw_product_adapters -p ironclaw_architecture --all-targets --all-features -- -D warnings
• git diff --check origin/reborn-integration...HEAD
• cargo check --workspace
• GitHub checks on 80e5e592 are green.

[henrypark133]

What looks good:

• The prior WIT blocker is addressed on head 80e5e592: adapter-manifest now carries paired declared-egress-targets, and egress-request uses a single egress-target-index.
• The old split declared-egress-hosts / declared-credential-handles and split indexes are now forbidden by wasm_product_adapter_wit_declares_egress_targets_as_paired_records.
• The Rust egress policy still enforces exact pairs, rejects unauthenticated requests to credential-only hosts, and the egress header/path tests now cover more host-managed and injection shapes.
• CI is green on the current head.

No verified findings.

Low-priority note:

• Gemini's open SystemClock::now_unix_seconds comment about unwrap_or(0) is not blocker-grade for this PR. It is a narrow clock-abnormality behavior in verifier glue, not a credential/auth bypass, and the verifier fails closed for normal current timestamps if the system clock is nonsensical.

Summary:

• Recommended verdict: Approve.
• Prior feedback status: addressed.
• Review coverage: current PR metadata/checks/reviews, open review threads, worktree-backed review of WIT, egress policy, egress DTOs, auth verifier, and architecture boundary tests.
• Verification: git diff --check origin/reborn-integration...HEAD, cargo test -p ironclaw_wasm_product_adapters --quiet, cargo test -p ironclaw_product_adapters egress --quiet, cargo test -p ironclaw_product_adapters auth --quiet, cargo test -p ironclaw_architecture wasm_product_adapter -- --nocapture, cargo test -p ironclaw_architecture reborn_crate_dependency_boundaries_hold -- --nocapture.