feat(OMN-15750): gateway attach/session control-plane effect node (G6)

[jonahgabriel]

Summary

First slice of the OMN-15739 ADOPT ruling (candidate A: edge-gateway agent -> OmniNode-owned attach ingress -> MSK server-side). Builds node_gateway_attach_effect, the attach/session control-plane node (G6 in docs/design/2026-08-08-gateway-node-architecture-lift.md) recommended by docs/design/2026-08-08-customer-cloud-connectivity-design.md's Open Question 2.

Three def-B EFFECT handlers, contract-driven config, secrets by ref:

• gateway.attach -- decodes a per-tenant Keycloak client-credentials access token, registers a tenant-bound ModelGatewaySession.
• gateway.heartbeat -- re-validates via RFC 7662 introspection on every tick. This is the revocation mechanism: disabling the tenant's Keycloak confidential client makes the next heartbeat observe active:false, tear the session down, and emit REVOKED -- independent of the token's own unexpired exp.
• gateway.detach -- explicit edge-initiated teardown.

Also in this PR:

• docker/docker-compose.gateway-attach-test-lane.yml (OMN-15752) -- a .201-side test-lane connector, parallel to and independent of the live bastion-path docker-compose.gateway.yml. The bastion is untouched.
• scripts/proof/gateway_attach_e2e_proof.py (OMN-15753) -- an e2e slice-proof harness skeleton (attach -> heartbeat -> Keycloak client disable -> heartbeat observes revocation), matching the existing e2e_cloud_workflow_harness.py convention: --live defaults off, live stage bodies raise StageNotImplementedError until run against a deployed node.

What is proven, and how (proof_class: code-only + receipt-bound)

• 16/16 unit tests pass, including test_heartbeat_after_keycloak_revocation_tears_down_session -- the literal handler-level revocation proof (introspection active:false -> session torn down, REVOKED event, gone from the store).
• mypy --strict clean on the new node package (22 files).
• ruff format + ruff check clean.
• Full local unit suite (23,188 tests, .200-shaped governed selector via the repo's own pre-push hook) green with this diff.
• pre-commit run full suite green, including the non-canonical-lifecycle-class ratchet, ONEX Architecture Validation, runtime_profiles validation, protocol-ownership, and subscribe-wiring-health gates -- each genuine finding fixed via the repo's existing allowlist mechanisms (see commit 2), not weakened.

What is NOT proven -- deploy and live e2e are explicitly out of scope for this PR:

• OMN-15754 (deploy to onex-dev) is not done. This PR is unmerged (by design -- PRs open, not merged, per operator instruction); onex-dev's running omninode-runtime/omninode-runtime-effects/omninode-runtime-worker pods are built from released/merged code. Standing doctrine (reference_runtime_deployment) is image-rebuild deploy, not hot-install -- there is no live-attach path for this node until it merges and a new image ships.
• OMN-15753's live half (real Kafka round trip + a real Keycloak client disable against a live tenant) did not run -- it requires the deployed node from OMN-15754. The harness is built and ready (scripts/proof/gateway_attach_e2e_proof.py --live ...).
• OMN-15751 (house tenant provisioning via POST /v1/tenants) is BLOCKED, not done. Live investigation on onex-dev (i-06169517a92b45f86, read-only + one kubectl exec diagnostic) found POST /v1/tenants sits behind m4_usage_metering_middleware, which requires an already-resolved tenant credential (Bearer JWT or x-api-key) -- it is not in PUBLIC_V1_PATHS. This is circular for a first/house tenant: there is no existing tenant credential to present. The two endpoints that are public (/v1/auth/provision, /v1/alpha/invite) create a Keycloak user (human login), not the P0B confidential client (machine client-credentials identity) that /v1/tenants -> _provision_tenant_credentials_p0b provisions and that this node's attach flow actually needs. Direct DB/Keycloak provisioning via kubectl exec into the onex-api pod was attempted but the SSM-wrapped kubectl exec output capture is unreliable (diagnostic echo markers did not reliably appear in captured stdout) -- root-causing that tooling gap was out of scope for this PR. No tenant was created, no Keycloak client was created, nothing was mutated on onex-dev.

Scope discipline

Does not touch node_bus_forwarder_effect, any file in the gateway Phase-0 lane (OMN-15740-44, wf_51aa94f0-854), the bastion (docker-compose.gateway.yml), or any AWS SG rule. No AWS IAM/DNS/SG mutation. No prod. Config is contract + overlay only; secrets resolve by ref via SecretResolver at the effect boundary -- no new env-var reads.

Tickets

OMN-15750, OMN-15752, OMN-15753 (code + proof harness). OMN-15751 and OMN-15754 remain open -- see blockers above.

Evidence-Source / OCC companion: not yet opened for this PR (informational-only for now; will pair before merge per repo Evidence-Source: OCC#<PR> receipt-gate convention if/when this heads toward merge).

Evidence-Ticket: OMN-15750
Evidence-Source: OCC#6224

Gate-fix pass (2026-08-12)

Root-caused and fixed the full red set (gh pr checks 2694 at pickup: CI Summary, Pin Reachability (OMN-15538), dispatch-parity-gate, gate / CodeRabbit Thread Check, imperative-contract-guard, runner-image-build-smoke, Topic Drift Check, Version Pin Compliance):

• Imperative Contract Guard (genuine, code fix): the new service_keycloak_token_validator.introspect() performed a raw httpx.AsyncClient call from a freestanding services/ module (outside node_*/handlers/), which scan_freestanding_imperative_io flags unconditionally regardless of DI shape. Moved the introspection call into HandlerGatewayHeartbeat._introspect (its sole caller) so the only I/O this node performs lives under handlers/; decode_claims (no I/O) stays in the service module. Declared metadata.transport_type: "HTTP" on the contract (sanctioned pattern, matches node_github_pr_poller_effect). Verified locally: check_imperative_contracts.py now reports live: 0 for this repo.
• dispatch-parity-gate (genuine, fixture regen): the PR's three new gateway.* dispatchers were never in the committed Mode-A oracle. Regenerated tests/fixtures/dispatch_parity/baseline-selection-v2.json per the test's own documented recipe; diff is scoped exactly to the three new node_gateway_attach_effect dispatcher entries.
• Topic Drift Check / Version Pin Compliance / Pin Reachability / runner-image-build-smoke (runner-infra faults, not code): byte-cited from each failing job's own log —
  • Topic Drift Check: The job has exceeded the maximum execution time of 10m0s + fetch-pack: invalid index-pack output / early EOF / RPC failed; curl 56 GnuTLS recv error (-54) during sibling-repo checkout.
  • Version Pin Compliance: uv sync hung mid-download (CACHE_ENABLED: false, UV_CONCURRENT_DOWNLOADS: 1) and was killed by the same 10-minute job timeout (The operation was canceled.).
  • Pin Reachability: onex_change_control @ 2dd26ade7c... — transport error: The read operation timed out resolving the pin (network, not a code defect).
  • runner-image-build-smoke: runner image shared_env_digest is stale (recorded=... recomputed=...) — the PR's 4-day-old head (41 commits behind dev) had a stale runner-image.lock.json relative to current dev.
    All four are consistent with a stale, contended head rather than a code defect. Fixed by rebasing onto origin/dev (git rebase origin/dev, clean, no conflicts) rather than a code change.
• CodeRabbit Thread Check (9 threads): 3 fixed in code (hardcoded topic literal removed from a docstring; heartbeat's unknown-session test now asserts the exact SessionNotFoundError instead of bare Exception; attach now rejects an already-expired token with TokenValidationError before registering a session, with a new regression test). 6 acknowledged with reasoning and resolved: the test-lane compose file's Kafka-bootstrap exposure (it's the OMN-15752 proof-only test lane, not the customer-facing edge connector, which doesn't exist yet); the e2e harness's missing stage_detach() (every stage in that skeleton raises StageNotImplementedError until OMN-15754 deploys — wiring a real detach stage now would be untestable); and four independent heavy-lift architecture items (DI-container handler construction, atomic session-lifecycle transitions, JWT signature verification via JWKS, and circuit-breaker-based Keycloak-outage-vs-revocation distinction) tracked in follow-up ticket OMN-15918.

Seams (OMN-14208) — claims produced by OMN-15877 vs consumed here

This node's decode_claims is the consumer side of whatever token OmniWeb mints (OMN-15877, PR omnibase_infra#2726). Field-by-field, checked against #2726's live diff (docker/keycloak/desired-clients.json, omniweb client):

Claim	Required by decode_claims	Emitted by #2726 (omniweb client)	Match
iss	yes	standard Keycloak claim	yes
sub	yes	standard Keycloak claim	yes
aud (must include gateway-attach)	yes (required_audience)	gateway-attach-audience mapper, NEW in #2726	yes
tenant_id	yes	tenant_id user-attribute mapper (pre-existing)	yes
tenant_slug	yes	tenant_slug user-attribute mapper (pre-existing)	yes
principal_id	yes	principal_id user-attribute mapper, NEW in #2726	yes
azp (-> ClaimSet.client_id)	yes	standard Keycloak claim = literal "omniweb" for every user of every tenant	field present, semantics do not match
exp	yes	standard Keycloak claim	yes

Wire shape: fully compatible — decode_claims will not raise a validation error against a real omniweb token once #2726 lands.

Credential-class design question (per OMN-15877's explicit requirement — recorded, not silently picked): this node (#2694) was built assuming a client-credentials machine token from a per-tenant confidential Keycloak client (the P0B chain) — see the contract's capabilities.introspection_revocation and every handler docstring: "disabling the tenant's Keycloak client" is the revocation mechanism, and session.keycloak_client_id (from azp) is assumed per-tenant. omniweb's actual client config is standardFlowEnabled: true, serviceAccountsEnabled: false — a user-session (authorization-code) token from one shared client, which #2726 extends with the gateway-attach audience rather than issuing a second, tenant-scoped credential (OMN-15877's option (a): "one token satisfies both validators"). Under that shape azp is always "omniweb", which breaks per-tenant revocation and the heartbeat's defense-in-depth client_id match as designed. This is an open PAIR_INCOMPATIBLE risk, not resolved by either PR — byte-cited comment posted on OMN-15877 (2026-08-12); resolution belongs to that ticket's confirmation loop with Daniyal's team, not a unilateral pick on either PR.

Summary by CodeRabbit

• New Features
  • Added gateway session lifecycle support for attach, heartbeat, and detach operations.
  • Added token validation, tenant-bound sessions, configurable expiration, and heartbeat status tracking.
  • Added session lifecycle events for attachment, heartbeat, degradation, revocation, and detachment.
  • Registered the gateway attach capability for runtime discovery and deployment.
• Tests
  • Added coverage for successful sessions, token revocation, invalid sessions, detachment, and validation failures.
• Documentation
  • Added a gateway attach end-to-end proof flow with dry-run support.

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 16 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: bdc8cdd7-79f1-4f0e-99d4-66e06efec06d

📥 Commits

Reviewing files that changed from the base of the PR and between f5d78db and 05a96a2.

📒 Files selected for processing (12)

• docker/runners/runner-image.lock.json
• pyproject.toml
• src/omnibase_infra/nodes/node_gateway_attach_effect/__init__.py
• src/omnibase_infra/nodes/node_gateway_attach_effect/contract.yaml
• src/omnibase_infra/nodes/node_gateway_attach_effect/handlers/handler_gateway_attach.py
• src/omnibase_infra/nodes/node_gateway_attach_effect/handlers/handler_gateway_heartbeat.py
• src/omnibase_infra/nodes/node_gateway_attach_effect/models/model_gateway_attach_config.py
• src/omnibase_infra/nodes/node_gateway_attach_effect/models/model_gateway_session_event.py
• src/omnibase_infra/nodes/node_gateway_attach_effect/services/service_keycloak_token_validator.py
• tests/fixtures/dispatch_parity/baseline-selection-v2.json
• tests/unit/nodes/node_gateway_attach_effect/test_handlers.py
• tests/unit/nodes/node_gateway_attach_effect/test_service_keycloak_token_validator.py

📝 Walkthrough

Walkthrough

Added a contract-driven gateway attach effect node. It validates tokens, stores tenant-bound sessions, handles attach, heartbeat, and detach operations, emits lifecycle events, and adds a dry-run proof harness with Docker Compose wiring.

Changes

Gateway attach control plane

Layer / File(s)	Summary
Session contracts and node registration src/omnibase_infra/nodes/node_gateway_attach_effect/..., src/omnibase_infra/validation/validation_exemptions.yaml	Added the node contract, Pydantic request and response models, session lifecycle enums, node class, public exports, and validation exemptions.
Token validation and session storage src/omnibase_infra/nodes/node_gateway_attach_effect/services/..., tests/unit/nodes/node_gateway_attach_effect/test_service_keycloak_token_validator.py	Added JWT claim validation, Keycloak introspection, an asynchronous session-store protocol, and an in-memory session store with unit tests.
Attach, heartbeat, and detach handlers src/omnibase_infra/nodes/node_gateway_attach_effect/handlers/..., tests/unit/nodes/node_gateway_attach_effect/test_handlers.py	Added session registration, heartbeat re-validation, revocation cleanup, detach processing, lifecycle events, and handler tests.
Gateway attach proof harness scripts/proof/gateway_attach_e2e_proof.py	Added dry-run planning and live-mode stage control for attach, heartbeat, optional revocation, and post-revocation verification.
Runtime and validation wiring docker/docker-compose.gateway-attach-test-lane.yml, pyproject.toml, scripts/check_subscribe_wiring_health.py, scripts/ci/infra-node-allowlist.txt	Registered the node entry point, added the test-lane service, and updated topic and infrastructure ownership allowlists.

Estimated code review effort: 4 (Complex) | ~60 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 8.16% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the new gateway attach/session control-plane effect node, which is the main change in the pull request.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch jonah/omn-15750-gateway-attach-ingress-node

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 9

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docker/docker-compose.gateway-attach-test-lane.yml`:
- Line 42: Remove the GATEWAY_ATTACH_TEST_LANE_BOOTSTRAP_SERVERS argument from
the edge-side connector configuration in the gateway attach test-lane setup.
Update the proof harness to use the gateway ingress API for edge requests, while
retaining Kafka bootstrap configuration only within infrastructure-side
components.

In `@scripts/proof/gateway_attach_e2e_proof.py`:
- Around line 146-152: Add an explicit stage_detach() call in run_live after the
active heartbeat and before optional revocation, register that stage in
STAGE_SURFACES, and make it consume detach_request_topic while asserting
DETACHED state and session removal.

In
`@src/omnibase_infra/nodes/node_gateway_attach_effect/handlers/handler_gateway_attach.py`:
- Around line 51-57: Update the handler constructors to accept
ModelONEXContainer instead of direct configuration and service dependencies,
resolving required values with container.get_service(...). In
handler_gateway_attach.py lines 51-57, resolve the configuration and
ProtocolGatewaySessionStore; in handler_gateway_detach.py lines 39-40, resolve
ProtocolGatewaySessionStore; and in handler_gateway_heartbeat.py lines 53-61,
resolve the configuration, ProtocolGatewaySessionStore, and secret resolver.
Update stored fields and constructor call sites as needed while preserving
handler behavior.
- Around line 72-91: Validate claims.expires_at_epoch before calculating TTL or
constructing ModelGatewaySession, and reject the request when the token is
already expired. Keep session registration through self._session_store.put
limited to tokens with a positive remaining lifetime.

In
`@src/omnibase_infra/nodes/node_gateway_attach_effect/handlers/handler_gateway_heartbeat.py`:
- Around line 74-114: The heartbeat handler must prevent stale reads from
resurrecting sessions after detach. In handler_gateway_heartbeat.py, make the
revoke and updated-session writes conditional on the session version/state read
before introspection, using a per-session lock or shared
compare-and-delete/compare-and-put lifecycle operation; in
handler_gateway_detach.py, replace the direct deletion with that same atomic
lifecycle operation so detach and heartbeat cannot interleave inconsistently.

In
`@src/omnibase_infra/nodes/node_gateway_attach_effect/models/model_gateway_session_event.py`:
- Line 8: Remove the hardcoded Kafka topic literal from the gateway session
event model and reference the topic exposed by the contract declaration instead.
Update the surrounding model definition in model_gateway_session_event.py to use
the existing generated or imported contract symbol, ensuring the contract YAML
remains the sole source of truth.

In
`@src/omnibase_infra/nodes/node_gateway_attach_effect/services/service_keycloak_token_validator.py`:
- Around line 57-111: Update decode_claims to verify the JWT signature using
trusted Keycloak keys and reject alg:none or altered signed claims before
constructing ClaimSet; validate issuer, audience, and expiration as part of this
flow. In
tests/unit/nodes/node_gateway_attach_effect/test_service_keycloak_token_validator.py
lines 59-87, replace the unsigned success fixture with a verified-token fixture
and add coverage rejecting alg:none tokens and post-signature claim changes.
- Around line 156-179: Update ServiceKeycloakTokenValidator to inherit from
MixinAsyncCircuitBreaker and route Keycloak introspection through its resilience
mechanism, raising InfraUnavailableError when the circuit opens or transport,
non-200, or malformed responses indicate infrastructure failure; return False
only for an explicit active: false response. Update
tests/unit/nodes/node_gateway_attach_effect/test_service_keycloak_token_validator.py
lines 191-222 to expect InfraUnavailableError for transport and upstream
failures, while preserving active: false as the sole revocation result.

In `@tests/unit/nodes/node_gateway_attach_effect/test_handlers.py`:
- Around line 216-227: Update test_heartbeat_unknown_session_raises to import
SessionNotFoundError from handler_gateway_heartbeat under an alias and pass that
exact exception type to pytest.raises instead of the broad Exception class.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 67c383aa-e4af-4319-8481-9170c6c251cd

📥 Commits

Reviewing files that changed from the base of the PR and between 211e81e and f5d78db.

⛔ Files ignored due to path filters (1)

• src/omnibase_infra/enums/generated/enum_omnibase_infra_topic.py is excluded by !**/generated/**

📒 Files selected for processing (33)

• docker/docker-compose.gateway-attach-test-lane.yml
• pyproject.toml
• scripts/check_subscribe_wiring_health.py
• scripts/ci/infra-node-allowlist.txt
• scripts/proof/gateway_attach_e2e_proof.py
• src/omnibase_infra/nodes/node_gateway_attach_effect/__init__.py
• src/omnibase_infra/nodes/node_gateway_attach_effect/contract.yaml
• src/omnibase_infra/nodes/node_gateway_attach_effect/handlers/__init__.py
• src/omnibase_infra/nodes/node_gateway_attach_effect/handlers/handler_gateway_attach.py
• src/omnibase_infra/nodes/node_gateway_attach_effect/handlers/handler_gateway_detach.py
• src/omnibase_infra/nodes/node_gateway_attach_effect/handlers/handler_gateway_heartbeat.py
• src/omnibase_infra/nodes/node_gateway_attach_effect/models/__init__.py
• src/omnibase_infra/nodes/node_gateway_attach_effect/models/enum_gateway_session_event_type.py
• src/omnibase_infra/nodes/node_gateway_attach_effect/models/enum_gateway_session_status.py
• src/omnibase_infra/nodes/node_gateway_attach_effect/models/model_gateway_attach_config.py
• src/omnibase_infra/nodes/node_gateway_attach_effect/models/model_gateway_attach_request.py
• src/omnibase_infra/nodes/node_gateway_attach_effect/models/model_gateway_attach_response.py
• src/omnibase_infra/nodes/node_gateway_attach_effect/models/model_gateway_detach_request.py
• src/omnibase_infra/nodes/node_gateway_attach_effect/models/model_gateway_detach_response.py
• src/omnibase_infra/nodes/node_gateway_attach_effect/models/model_gateway_heartbeat_request.py
• src/omnibase_infra/nodes/node_gateway_attach_effect/models/model_gateway_heartbeat_response.py
• src/omnibase_infra/nodes/node_gateway_attach_effect/models/model_gateway_session.py
• src/omnibase_infra/nodes/node_gateway_attach_effect/models/model_gateway_session_event.py
• src/omnibase_infra/nodes/node_gateway_attach_effect/node.py
• src/omnibase_infra/nodes/node_gateway_attach_effect/services/__init__.py
• src/omnibase_infra/nodes/node_gateway_attach_effect/services/protocol_gateway_session_store.py
• src/omnibase_infra/nodes/node_gateway_attach_effect/services/service_keycloak_token_validator.py
• src/omnibase_infra/nodes/node_gateway_attach_effect/services/store_gateway_session_memory.py
• src/omnibase_infra/validation/validation_exemptions.yaml
• tests/unit/contracts/test_protocol_ownership.py
• tests/unit/nodes/node_gateway_attach_effect/__init__.py
• tests/unit/nodes/node_gateway_attach_effect/test_handlers.py
• tests/unit/nodes/node_gateway_attach_effect/test_service_keycloak_token_validator.py

[github-actions]

✅ Hostile Reviewer — PASSED

Blocking findings (critical): 0
Total findings: 0
Models succeeded: qwen3-review,qwen3-review-b

---

Gate semantics (pilot phase)

Verdict	Meaning	Blocks merge?
passed	No critical findings	No
blocked	CRITICAL findings found	Yes
degraded	All models unavailable (infra)	No (pilot)

Powered by omniintelligence.review_pairing.cli_review — node-based adversarial review via HandlerLlmCliSubprocess (OMN-8468/OMN-8524)